Game State

Get live game state (scores, clocks, periods) aggregated across all sportsbooks. Data is merged from multiple books using a “max score + priority fill” strategy for maximum accuracy.

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

Authentication

Requires API key via X-API-Key header, Authorization: Bearer header, or api_key query param. Enterprise tier required.

Endpoints

List Available Sports

GET /api/v1/gamestate

Returns a summary of all sports with active live game state data, including event counts and TTLs.

Get Sport Game State

GET /api/v1/gamestate/{sport}

Returns merged live game state for all events in the specified sport.

Path Parameters

Query Parameters (Sport Endpoint)

Response Headers

All responses include standard rate limit and metadata headers:

Game State Object

Each event in the response contains merged state from multiple sportsbooks:

Sport-Specific Fields

Additional fields may be present depending on the sport:

Example Requests

List available sports

curl -X GET "https://api.sharpapi.io/api/v1/gamestate" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  'https://api.sharpapi.io/api/v1/gamestate',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data, meta } = await response.json();
console.log(`${meta.sport_count} sports, ${meta.total_events} live events`);

import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/gamestate',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
result = response.json()
for sport in result['data']['sports']:
    print(f"{sport['sport']}: {sport['event_count']} events")

Response

{
  "success": true,
  "data": {
    "sports": [
      { "sport": "soccer", "event_count": 54, "ttl": 59 },
      { "sport": "basketball", "event_count": 23, "ttl": 59 },
      { "sport": "tennis", "event_count": 15, "ttl": 59 },
      { "sport": "baseball", "event_count": 9, "ttl": 59 },
      { "sport": "hockey", "event_count": 1, "ttl": 59 },
      { "sport": "golf", "event_count": 1, "ttl": 59 }
    ]
  },
  "meta": {
    "sport_count": 6,
    "total_events": 103,
    "updated_at": "2026-03-08T18:07:44.733Z"
  }
}

Get basketball game state (NBA only)

curl -X GET "https://api.sharpapi.io/api/v1/gamestate/basketball?league=nba" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  'https://api.sharpapi.io/api/v1/gamestate/basketball?league=nba',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data, meta } = await response.json();
 
for (const [eventId, state] of Object.entries(data)) {
  console.log(`${state.homeTeam} ${state.homeScore} - ${state.awayScore} ${state.awayTeam} (${state.gamePeriod} ${state.gameClock})`);
}

import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/gamestate/basketball',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'league': 'nba'}
)
result = response.json()
 
for event_id, state in result['data'].items():
    print(f"{state['homeTeam']} {state['homeScore']}-{state['awayScore']} {state['awayTeam']} ({state['gamePeriod']} {state['gameClock']})")

Response

{
  "success": true,
  "data": {
    "nba_cavaliers_celtics_2026-03-08": {
      "isLive": true,
      "homeTeam": "CLE Cavaliers",
      "awayTeam": "BOS Celtics",
      "sport": "basketball",
      "league": "nba",
      "homeScore": 50,
      "awayScore": 33,
      "gamePeriod": "Q2",
      "gameClock": "2:29",
      "possession": "home",
      "lastPlay": "REBOUND: Evan Mobley defensive rebound",
      "foulsHome": 5,
      "foulsAway": 3,
      "primaryBook": "draftkings",
      "bookCount": 4
    }
  },
  "meta": {
    "sport": "basketball",
    "event_count": 1,
    "filters": {
      "league": "nba",
      "live": null
    },
    "updated_at": "2026-03-08T18:07:54.694Z"
  }
}

Merge Strategy

Game state is aggregated from multiple sportsbooks using a “max score + priority fill” strategy:

1. Primary book selection: The book with the highest total score (homeScore + awayScore) is selected as primary. On tie, book priority order is used: DraftKings > FanDuel > BetRivers > Caesars > Bovada > Betway > Bet365 > Fliff > Kalshi > ProphetX.
2. All fields from primary: The primary book’s state becomes the base.
3. Gap filling: Any null fields are filled from other books in priority order.
4. Metadata: primaryBook and bookCount are added to indicate data provenance.

Data Freshness

Game state updates every 1-2 seconds via pub/sub-driven aggregation. The gamestate:{sport} keys have a 60-second TTL and are refreshed continuously while live events are in progress.

Error Responses

401 Unauthorized

{
  "error": {
    "code": "missing_api_key",
    "message": "API key required",
    "docs": "https://sharpapi.io/docs/authentication"
  }
}

403 Forbidden (Tier Insufficient)

{
  "error": {
    "code": "feature_not_available",
    "message": "Live game state requires Enterprise tier"
  }
}

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "No game state available for sport: cricket"
  }
}

Related Endpoints

• Events — List events with filtering
• Event Details — Get details for a specific event
• Odds Snapshot — Get odds with live game state fields
• SSE Stream — Real-time streaming (supports ?channel=gamestate)