Skip to Content

Events

Einheitlicher Endpoint zum Auflisten und Suchen von Events mit Filterung, Paginierung und Suche.

GET /api/v1/events

Dieser Endpoint ersetzt die bisherigen Endpoints /schedule, /events/live und /events/search. Die gesamte Funktionalität dieser Endpoints ist nun hier über Query-Parameter verfügbar. Siehe Migrationshinweise unten.

AuthentifizierungPermalink zu diesem Abschnitt

Erfordert einen API-Key über den X-API-Key-Header, den Authorization: Bearer-Header oder den api_key-Query-Parameter. Verfügbar in allen Tarifen.

Query-ParameterPermalink zu diesem Abschnitt

ParameterTypStandardBeschreibung
sportstringalleFilter nach Sportart. Kommagetrennt für mehrere Werte (z. B. basketball,football). Nur Sport-IDs; eine Liga-ID wie nba gehört in league (Details).
leaguestringalleFilter nach Liga. Kommagetrennt für mehrere Werte (z. B. nba,nfl)
sportsbookstringalleFilter nach Sportsbook (z. B. draftkings,pinnacle)
statusstring—Filter nach Lebenszyklus-Status: upcoming, live oder final. Weglassen für die Standardmenge (upcoming + live). final liefert stattdessen gespeicherte abgeschlossene Events. Ein unbekannter Wert wird mit 400 validation_error abgelehnt.
is_liveboolean—true = nur Live, false = nur Prematch, weglassen = beide
datestring—Filter nach Datum im Format YYYY-MM-DD
qstring—Suchanfrage, die Teamnamen oder Eventnamen abgleicht
limitinteger50Ergebnisse pro Seite (max. 200)
offsetinteger0Paginierungs-Offset

Query-Parameter verwenden die Singularform und kommagetrennte Werte für mehrere Werte: sport=basketball,football, nicht sports=basketball&sports=football.

Response-HeaderPermalink zu diesem Abschnitt

Alle Antworten enthalten standardmäßige Rate-Limit- und Metadaten-Header:

HeaderBeschreibung
X-RateLimit-LimitMaximale Anfragen pro Minute für Ihren Tarif
X-RateLimit-RemainingVerbleibende Anfragen im aktuellen Zeitfenster
X-RateLimit-ResetUnix-Zeitstempel, wann das Rate-Limit-Fenster zurückgesetzt wird
X-Data-DelayDatenverzögerung für Ihren Tarif (z. B. 0s, 60s)
X-Request-IdEindeutige Request-Kennung zur Fehlersuche

Event-ObjektPermalink zu diesem Abschnitt

FeldTypBeschreibung
idstringKanonische Event-Kennung — für jedes Sportsbook, das dieses Event abdeckt, identisch. Verwenden Sie diese als Primärschlüssel für den Abgleich zwischen Sportsbooks. Siehe Event-Matching.
external_idsobjectZuordnung von Sportsbook-ID zur nativen Event-ID des jeweiligen Sportsbooks (z. B. {"draftkings": "33483153"}). Verwenden Sie diese für Deep Links zurück zu den Sportsbook-Seiten.
sportstringSportart-Kennung (z. B. basketball, football)
leaguestringLiga-Slug (z. B. nba, nfl)
home_teamstringName des Heim-Teams
away_teamstringName des Auswärts-Teams
start_timestringISO-8601-Startzeit des Events. Fehlt bei einem abgeschlossenen Event aus dem Retention-Speicher — prüfen Sie auf das Vorhandensein des Schlüssels, nicht auf status.
completed_atstringISO-8601-Abschlusszeit. Nur bei Zeilen mit status: "final" vorhanden.
statusstringEvent-Status: upcoming, live oder final. final wird nur bei Anforderung mit ?status=final zurückgegeben. Der Status ist live, wenn unser Spiel-Tracking zeigt, dass das Spiel läuft, oder wenn mehrere Sportsbooks Live-Preise darauf anbieten.
is_livebooleanOb das Spiel live ist: true, wenn status live ist.
live_book_countintegerWie viele Sportsbooks mindestens einen Live-Preis auf dieses Event haben. Immer vorhanden, 0, wenn keines. Kann auch über 0 liegen, wenn das Event nicht live ist. Bei einem live-Event bedeutet 0, dass allein unser Spiel-Tracking zeigt, dass das Spiel läuft.
book_countintegerAnzahl der Sportsbooks mit Quoten für dieses Event
marketsstring[]Sortiertes Array der verfügbaren Markttypen (z. B. ["moneyline", "point_spread", "total_points"])
booksstring[]Sortiertes Array der Sportsbook-IDs mit Quoten für dieses Event
game_stateobject | undefinedLive-Spielstand (nur vorhanden bei Live-Events mit Ständen)

Abgeschlossene Events. ?status=final liefert gespeicherte abgeschlossene Events, neueste zuerst — eine eigene Ergebnismenge, die nicht Teil der ungefilterten Liste ist. Diese Zeilen lassen start_time weg (für sie wird keine Startzeit gespeichert) und enthalten stattdessen completed_at. Ein gerade beendetes Event, dessen Quoten noch im Cache liegen, behält seine echte start_time — prüfen Sie daher, ob der Schlüssel vorhanden ist, statt auf status zu verzweigen.

Game-State-ObjektPermalink zu diesem Abschnitt

Enthalten, wenn das Event live ist und Score-Daten vorliegen:

FeldTypBeschreibung
home_scorenumberPunktzahl des Heim-Teams
away_scorenumber | nullPunktzahl des Auswärts-Teams
periodstring | nullAktuelle Periode (z. B. Q3, 2nd, 3rd Period)
clockstring | nullVerbleibende Zeit (z. B. 5:42)
score_typestringScore-Typ (z. B. game_points, match)
possessionstring | nullTeam mit Ballbesitz (home oder away)
is_timeoutboolean | nullGibt an, ob ein Timeout läuft
power_playstring | nullPower-Play-Information (home oder away, Eishockey)
last_playstring | nullBeschreibung des letzten Spielzugs

BeispielanfragenPermalink zu diesem Abschnitt

Bevorstehende NBA- und NFL-Events auflistenPermalink zu diesem Abschnitt

curl -X GET "https://api.sharpapi.io/api/v1/events?sport=basketball,football&league=nba,nfl&limit=20" \ -H "X-API-Key: YOUR_API_KEY"

Nur Live-Events abrufenPermalink zu diesem Abschnitt

curl -X GET "https://api.sharpapi.io/api/v1/events?is_live=true" \ -H "X-API-Key: YOUR_API_KEY"

Nach einem Team suchenPermalink zu diesem Abschnitt

curl -X GET "https://api.sharpapi.io/api/v1/events?q=celtics" \ -H "X-API-Key: YOUR_API_KEY"

Nach Datum und Sportsbook filternPermalink zu diesem Abschnitt

curl -X GET "https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel" \ -H "X-API-Key: YOUR_API_KEY"

AntwortPermalink zu diesem Abschnitt

Erfolg (200)Permalink zu diesem Abschnitt

{ "data": [ { "id": "evt_nba_bos_lal_20260208", "external_ids": { "draftkings": "33483200", "fanduel": "nba-bos-lal-20260208" }, "sport": "basketball", "league": "nba", "home_team": "Boston Celtics", "away_team": "Los Angeles Lakers", "start_time": "2026-02-08T19:30:00Z", "status": "upcoming", "is_live": false, "live_book_count": 0, "book_count": 6, "markets": ["moneyline", "point_spread", "total_points"], "books": ["betmgm", "caesars", "draftkings", "fanduel"] }, { "id": "evt_nba_gsw_mia_20260208", "external_ids": { "draftkings": "33483205" }, "sport": "basketball", "league": "nba", "home_team": "Golden State Warriors", "away_team": "Miami Heat", "start_time": "2026-02-08T22:00:00Z", "status": "upcoming", "is_live": false, "live_book_count": 0, "book_count": 5, "markets": ["moneyline", "point_spread", "total_points"], "books": ["betmgm", "draftkings", "fanduel"] } ], "meta": { "count": 2, "total": 43, "pagination": { "limit": 50, "offset": 0, "has_more": true, "next_offset": 50 }, "updated_at": "2026-02-08T12:00:00Z", "filters": { "sport": ["basketball"], "league": ["nba"] } } }

Leere Ergebnisse (200): meta.storePermalink zu diesem Abschnitt

Wenn /events null Events zurückgibt, wird ein meta.store-Block angehängt, der den Grund nennt — mit demselben reason-Vokabular wie /odds, sodass eine Verzweigung beide Endpoints abdeckt. data ist [] (vor September 2026 wurde es in der Standardliste als null serialisiert; ?status=final lieferte bereits []), und pagination trägt count: 0 und total: 0:

{ "data": [], "meta": { "store": { "ready": true, "events": 11064, "reason": "no_match" } }, "pagination": { "limit": 50, "offset": 0, "count": 0, "total": 0, "has_more": false, "next_offset": null }, "updated_at": "2026-09-07T02:41:18.552Z" }
reasonBedeutungWas zu tun ist
warmingDie antwortende Instanz hat seit ihrem letzten Moduswechsel keinen Aktualisierungszyklus abgeschlossen — es ist noch nichts geladenErneut versuchen
store_emptyDie Instanz ist bereit, aber der Event-Cache, aus dem diese Seite gebaut wurde, ist leerErneut versuchen — die leere Seite nicht als maßgeblich behandeln
no_matchDie Instanz ist bereit und der Cache ist befüllt; Ihre Filter haben nichts getroffenMaßgeblich — ein erneuter Versuch ändert die Antwort nicht
FeldTypBedeutung
readybooleanSeit dem letzten Moduswechsel der Instanz wurde mindestens ein Aktualisierungszyklus abgeschlossen.
eventsintegerEvents im Cache, aus dem diese Seite gebaut wurde, unabhängig von Ihren Filtern. Seiten mit ?status=final werden aus dem Store abgeschlossener Events bedient und melden stattdessen dessen Größe.
reasonstringwarming, store_empty oder no_match — siehe oben.

meta.store ist nur bei leeren Ergebnissen vorhanden; eine Antwort mit Events ist unverändert. Es gibt hier bewusst keine generation — dieser Zähler gehört zum Quoten-Store, der diesen Endpoint nicht speist. Ein unbekannter Wert für league oder sportsbook wird mit 400 invalid_filter abgewiesen und nicht mit einer leeren Seite beantwortet.

FehlerantwortenPermalink zu diesem Abschnitt

401 Unauthorized

Ohne Schlüssel wird missing_api_key zurückgegeben; ein ungültiger Schlüssel ergibt invalid_api_key.

{ "error": { "code": "missing_api_key", "message": "API key required. Pass via X-API-Key header, api_key query parameter, or Bearer token.", "docs": "https://docs.sharpapi.io/en/authentication" } }

400 Bad Request

{ "error": { "code": "validation_error", "message": "Invalid date format. Use YYYY-MM-DD.", "docs": "https://docs.sharpapi.io/en/api-reference/events" } }

429 Rate Limited

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Upgrade your tier for higher limits.", "docs": "https://docs.sharpapi.io/en/pricing" } }

Migration von früheren EndpointsPermalink zu diesem Abschnitt

Mehrere veraltete Event-Unterpfade aus früheren API-Versionen werden als Hinweis auf die Veraltung beibehalten — beim Aufruf wird 410 Gone mit einem maschinenlesbaren Hinweis zurückgegeben, der auf den korrekten Endpoint verweist.

Veralteter PfadStattdessen verwenden
GET /events/search?q=celticsGET /events?q=celtics
GET /events/listGET /events
GET /events/allGET /events
GET /events/findGET /events

Aufbau der 410-AntwortPermalink zu diesem Abschnitt

{ "error": { "code": "unknown_endpoint", "message": "There is no /api/v1/events/search endpoint. Use GET /api/v1/events — results can be filtered with ?sport=, ?league=, and ?book= query parameters.", "correct_endpoint": "/api/v1/events", "docs": "https://docs.sharpapi.io/api-reference" } }

Antworten vor v1 verwendeten Feldnamen in camelCase (homeTeam, awayTeam, isLive, bookCount). Die v1-API verwendet ausschließlich snake_case (home_team, away_team, is_live, book_count). Aktualisieren Sie Ihren Client-Code entsprechend.

Wesentliche Änderungen gegenüber früheren VersionenPermalink zu diesem Abschnitt

  • Feldnamen sind nun in snake_case (z. B. home_team anstelle von homeTeam)
  • Die Antwort verwendet das standardmäßige data/meta-Envelope anstelle eines events-Arrays auf oberster Ebene
  • Query-Parameter verwenden die Singularform (sport anstelle von sports)
  • Die Basis-URL lautet https://api.sharpapi.io (nicht https://sharpapi.io)
  • Die Paginierung umfasst nun die Felder has_more und next_offset

Event-Matching über mehrere Sportsbooks hinwegPermalink zu diesem Abschnitt

Das Feld id ist eine kanonische Event-Kennung — dasselbe reale Event erhält dieselbe id, unabhängig davon, von welchem Sportsbook es stammt. Verwenden Sie sie als Primärschlüssel beim Erstellen von Vergleichstools über mehrere Sportsbooks hinweg. Das Feld external_ids ordnet jedem Sportsbook seine native Event-ID für Deep Links zu.

Vollständige Details zur Funktionsweise kanonischer IDs finden Sie unter Event-Matching.

Verwandte EndpointsPermalink zu diesem Abschnitt

Last updated on