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}

Authentication

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 Parameters

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

Response Envelope

{
  "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 Fields

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 present

Temporal (most team sports)

Situational

Sport-specific

Freshness

Example Requests

# 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 Response

{
  "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 Model

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.

Streaming

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 & Quotas

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.

Troubleshooting

• 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.