Live Game State

Aggregated live game state — scores, periods, clocks, possession, and sport-specific situational data — merged across sportsbooks into a single authoritative view per event. One row per live fixture, consensus-selected from the books covering it.

GET /api/v1/gamestate
GET /api/v1/gamestate/{sport}

AuthenticationPermalink for this section

Requires API key. Available on the Game State add-on ($79/mo) or the Enterprise tier. Keys without either receive 403 tier_restricted with addon: "game_state" in the error body. Add the add-on from the billing page  on any paid plan (Hobby / Pro / Sharp); Enterprise keys get it included.

Live game state also streams over the gamestate channel on SSE and WebSocket — see Streaming below. (Streaming access requires the WebSocket add-on or Enterprise, in addition to the Game State requirement above.)

Path ParametersPermalink for this section

Without the path parameter, returns every sport with live events.

Response EnvelopePermalink for this section

{
  "data": {
    "<sport>": {
      "<event_id>": { ...event state... }
    }
  },
  "updated_at": "2026-04-23T23:55:01.234Z"
}

Every event state is keyed by its canonical event_id within its sport bucket. updated_at is the server’s time when this response was built — use it to gauge freshness if polling.

Event State FieldsPermalink for this section

Every field is optional except where noted. Presence varies by sport — tennis events carry sets_home / server; hockey events carry power_play; soccer events carry corners_* / yellow_cards_*; etc.

Always presentPermalink for this section

Temporal (most team sports)Permalink for this section

SituationalPermalink for this section

Sport-specificPermalink for this section

Baseball in_play blockPermalink for this section

Per-at-bat state on live baseball events. Populated whenever the contributing book exposes pitch-level data (currently FanDuel, BetMGM, Betway, theScoreBet, and ProphetX); omitted otherwise. Inner field names are camelCase — they are not snake-cased by the API transform.

"in_play": {
  "outs": 1,                                                 // 0, 1, or 2
  "balls": 2,                                                // 0-3
  "strikes": 1,                                              // 0-2
  "runners": {"first": true, "second": false, "third": true},
  "currentPitcher": "Zach Agnos",                            // pitcher on the mound now
  "currentBatter": "Tyrone Taylor"                           // active hitter
}

FreshnessPermalink for this section

Example RequestsPermalink for this section

# All live events across every sport
curl "https://api.sharpapi.io/api/v1/gamestate" \
  -H "X-API-Key: YOUR_API_KEY"
 
# One sport
curl "https://api.sharpapi.io/api/v1/gamestate/soccer" \
  -H "X-API-Key: YOUR_API_KEY"

const res = await fetch('https://api.sharpapi.io/api/v1/gamestate/soccer', {
  headers: { 'X-API-Key': process.env.SHARPAPI_KEY }
});
const { data, updated_at } = await res.json();
for (const [eventId, state] of Object.entries(data.soccer ?? {})) {
  if (state.stale || state.aggregator_stale) continue;  // skip lagging rows
  console.log(
    `${state.home_team} ${state.home_score}-${state.away_score} ${state.away_team}`,
    `(${state.game_period ?? '?'} ${state.game_clock ?? ''}, ${state.primary_book})`
  );
}

import httpx, os
r = httpx.get(
    "https://api.sharpapi.io/api/v1/gamestate/soccer",
    headers={"X-API-Key": os.environ["SHARPAPI_KEY"]},
)
body = r.json()
for event_id, state in body["data"].get("soccer", {}).items():
    if state.get("stale") or state.get("aggregator_stale"):
        continue  # skip lagging rows
    print(
        f"{state['home_team']} {state['home_score']}-{state['away_score']} "
        f"{state['away_team']} ({state.get('game_period')} "
        f"{state.get('game_clock','')}, {state['primary_book']})"
    )

Example ResponsePermalink for this section

{
  "data": {
    "soccer": {
      "argentina_-_primera_division_bocajuniors_defensayjusticia_2026-04-23": {
        "home_team": "Defensa y Justicia",
        "away_team": "Boca Juniors",
        "sport": "soccer",
        "league": "argentina_-_primera_division",
        "home_score": 0,
        "away_score": 1,
        "game_period": "2H",
        "game_clock": "49:06",
        "is_live": true,
        "possession": "away",
        "corners_home": 1,
        "corners_away": 0,
        "fouls_home": 0,
        "fouls_away": 0,
        "yellow_cards_home": 0,
        "yellow_cards_away": 0,
        "red_cards_home": 0,
        "red_cards_away": 0,
        "primary_book": "draftkings",
        "book_count": 6
      },
      "chile_-_primera_division_concepcion_palestino_2026-04-24": {
        "home_team": "Palestino",
        "away_team": "Concepción",
        "sport": "soccer",
        "league": "chile_-_primera_division",
        "home_score": 0,
        "away_score": 0,
        "is_live": true,
        "primary_book": "unibet",
        "book_count": 1,
        "stale": true
      }
    }
  },
  "updated_at": "2026-04-23T23:55:01.234Z"
}

Cross-Book Merge ModelPermalink for this section

Each event’s fields are merged from every sportsbook’s livestate snapshot via a three-class algorithm:

• Class A — Scores are picked by consensus: among books at the most advanced period rank, the highest-total score with ≥2 backers wins. A single book reporting an outlier score (common in the first seconds of a score change, or from a misbehaving adapter) is rejected.
• Class B — Temporal fields (game_period, game_clock) are selected by sport-aware clock direction — countdown vs countup — and period rank.
• Class C — Situational fields (possession, corners_*, etc.) are priority-filled from a fixed book ranking.

primary_book reports which book the winning scores came from. book_count is the total number of books that contributed any state for the event at merge time.

StreamingPermalink for this section

Every update that the REST endpoint would surface on the next poll also fires a gamestate:update event on the streaming channels:

• SSE: GET /api/v1/stream/gamestate
• WebSocket: subscribe to {channels: ["gamestate"]} on wss://ws.sharpapi.io/ws

Streaming clients receive an initial gamestate:snapshot with the full current state (a flat list of event rows), then gamestate:update events carrying changed rows as they merge, and gamestate:removed events when events drop from the live set.

Rate Limits & QuotasPermalink for this section

Rate limits follow your base tier, not the add-on — Hobby keys keep their 120 req/min, Pro keep 300, Sharp keep 1,000, Enterprise custom. See Pricing . /gamestate counts the same as other REST calls toward the per-minute quota.

TroubleshootingPermalink for this section

• 403 tier_restricted with addon: "game_state" — your key doesn’t have the Game State add-on. Add it from Billing  for $79/mo, or upgrade to Enterprise.
• Empty data object — no live events in scope. This is common between events on smaller sport schedules. Poll again.
• Events with stale: true — the primary book has gone silent. Scores may lag; consider filtering them out or surfacing a UI indicator.
• Events with aggregator_stale: true — the SharpAPI aggregator hasn’t refreshed that sport in >30s. If persistent, reach out to support; a brief bump can happen during redeploys.
• Same match appears twice under different event_ids — known limitation for some regional leagues where sportsbooks use inconsistent league naming. Use (home_team, away_team) as a secondary dedup key on the client until the remaining alias gaps close.