> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise.predexon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Live States
> List live score and game-state snapshots by sports game_id
## Overview
Returns live game-state snapshots keyed by canonical sports `game_id`.
This endpoint is intentionally separate from market discovery. Use `/v2/sports/games` and `/v2/sports/markets` to discover tradeable outcomes, then use `/v2/sports/live` to read score, period, clock, winner, and source reliability for the broad real-world game.
If live state is not yet available for a game, games can still appear with `reliability.state = "no_data"` and null score fields.
For the broader model and source reliability semantics, see [Sports Live State](/concepts/sports-live-state). For the websocket contract, see [Sports Live WebSocket](/api-reference/sports/live-websocket).
## Query Parameters
| Param | Type | Default | Description |
| ----------------- | ------- | ------- | -------------------------------------------------------------------- |
| `sport` | string | - | Filter by sport: `basketball`, `soccer`, `hockey`, `baseball`. |
| `league` | string | - | Filter by league code, e.g. `mlb`, `nba`, `epl`. |
| `game_date` | string | - | Exact game date, `YYYY-MM-DD`. |
| `live_only` | boolean | `false` | Only return games currently marked live. |
| `include_sources` | boolean | `false` | Include source-level snapshots under `sources[]`. |
| `limit` | int | `50` | 1-200. |
| `pagination_key` | string | - | Opaque cursor from the previous response. Omit on the first request. |
## Response Fields
| Field | Type | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `game_id` | string | Broad real-world sports fixture ID. |
| `league` | string | League code. |
| `sport` | string | Sport name. |
| `game_date` | string | Calendar date, `YYYY-MM-DD`. |
| `title` | string | Display title. |
| `home_team` | object? | Home team when known by source mapping. |
| `away_team` | object? | Away team when known by source mapping. |
| `participants[]` | array | Known participants from canonical sports game metadata. |
| `status` | string | Current aggregate status or canonical market status fallback. |
| `status_text` | string? | Source-derived display status, e.g. `"Full-Time"`. |
| `live` | boolean | Whether the game is currently live. |
| `ended` | boolean | Whether the game has ended. |
| `period` | string? | Current period/inning/half/quarter. |
| `clock` | string? | Current game clock where applicable. |
| `score.home` | number? | Home score when home/away mapping is known. |
| `score.away` | number? | Away score when home/away mapping is known. |
| `score.display` | string? | Source/aggregate display score. |
| `winner` | string? | `home`, `away`, `draw`, or a source-native winner value. |
| `last_play` | object? | Latest notable play when available. When present, it maps to the most recent item in `significant_events[]`. It can be `null` when no notable incident has happened yet or the source has not supplied one at that time. |
| `significant_events[]` | array | Normalized key incident list. Can include score changes, cards, substitutions, period events, game start/end, or source-supported `other` events. Empty when no incidents are available. |
| `reliability` | object | Aggregate source reliability state. |
| `sources[]` | array | Source-level snapshots when `include_sources=true`. |
| `updated_at` | string? | Last aggregate update timestamp. |
## Event List Coverage
The event list uses the `significant_events[]` field on each live-state object. It is intended for key incidents, not every vendor-specific stat or full box score.
Supported normalized event types include:
| Event type | Meaning |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `score_change` | Scoring event, including soccer goals, basketball made shots/free throws, or other source-supported score changes. |
| `yellow_card` | Soccer yellow card. |
| `red_card` | Soccer red card. |
| `substitution` | Source-supplied substitution event. |
| `period_start` | Start of a period, half, quarter, map, or similar segment when exposed by the source. |
| `period_end` | End of a period, half, quarter, map, or similar segment when exposed by the source. |
| `game_start` | Game started. |
| `game_end` | Game ended or final status reached. |
| `other` | Source-supplied incident that does not map cleanly to a standard type yet. |
Game coverage follows the same matched sports universe as [`GET /v2/sports/games`](/api-reference/sports/games) and the [sports venue coverage matrix](/concepts/sports-markets#venue-coverage). Incident availability is source- and sport-dependent. Kalshi soccer milestones commonly include goals, cards, substitutions, period events, and game-end events. Kalshi basketball can include made shots/free throws and period boundaries. Baseball play-by-play may be available for some games, but typed key incidents are less consistent. If no key incidents are available for a game, `significant_events` is returned as `[]`.
## Reliability States
| State | Meaning |
| --------------- | --------------------------------------------------------------------------- |
| `no_data` | The game exists, but no source has written live state. |
| `single_source` | One source has current state. |
| `confirmed` | Two or more sources agree on material fields. |
| `conflict` | Sources disagree on material fields such as score, winner, or ended status. |
| `stale` | Latest available source state is too old for a live game. |
## Example
`GET /v2/sports/live?league=mlb&limit=1`
```json theme={null}
{
"live_states": [
{
"game_id": "mlb-ari-pit-2026-05-07",
"league": "mlb",
"sport": "baseball",
"game_date": "2026-05-07",
"title": "Arizona Diamondbacks vs Pittsburgh Pirates",
"home_team": null,
"away_team": null,
"participants": [
{ "code": "ari", "name": "Arizona Diamondbacks" },
{ "code": "pit", "name": "Pittsburgh Pirates" }
],
"status": "open",
"status_text": null,
"live": false,
"ended": false,
"period": null,
"clock": null,
"score": {
"home": null,
"away": null,
"display": null
},
"winner": null,
"last_play": null,
"significant_events": [],
"reliability": {
"state": "no_data",
"source_count": 0,
"sources": [],
"conflict": false,
"stale": true
},
"sources": [],
"updated_at": null
}
],
"pagination": {
"limit": 1,
"has_more": true,
"pagination_key": "eyJybyI6MS..."
}
}
```
## OpenAPI
````yaml GET /v2/sports/live
openapi: 3.1.0
info:
title: Predexon Enterprise API
description: Unified cross-venue prediction market discovery
version: 1.0.0
servers:
- url: https://api.predexon.com
security:
- apiKey: []
paths:
/v2/sports/live:
get:
tags:
- sports
summary: List Live States
description: >-
List sports live score and game-state snapshots keyed by canonical
sports game_id.
operationId: list_live_states_v2_sports_live_get
parameters:
- name: sport
in: query
required: false
schema:
type: string
enum:
- basketball
- soccer
- hockey
- baseball
description: Filter by sport.
- name: league
in: query
required: false
schema:
type: string
description: Filter by league code.
- name: game_date
in: query
required: false
schema:
type: string
description: Exact game date (YYYY-MM-DD).
- name: live_only
in: query
required: false
schema:
type: boolean
default: false
description: Only return games currently marked live.
- name: include_sources
in: query
required: false
schema:
type: boolean
default: false
description: Include source-level live state snapshots.
- name: limit
in: query
required: false
schema:
type: integer
default: 50
minimum: 1
maximum: 200
description: Max live states to return.
- name: pagination_key
in: query
required: false
schema:
type: string
description: Cursor from the previous response. Omit on the first request.
responses:
'200':
description: Successful response
content:
application/json:
schema: {}
example:
live_states:
- game_id: mlb-ari-pit-2026-05-07
league: mlb
sport: baseball
game_date: '2026-05-07'
title: Arizona Diamondbacks vs Pittsburgh Pirates
home_team: null
away_team: null
participants:
- code: ari
name: Arizona Diamondbacks
- code: pit
name: Pittsburgh Pirates
status: open
status_text: null
live: false
ended: false
period: null
clock: null
score:
home: null
away: null
display: null
winner: null
ended_at: null
last_play: null
significant_events: []
reliability:
state: no_data
source_count: 0
sources: []
conflict: false
stale: true
sources: []
updated_at: null
pagination:
limit: 1
has_more: true
pagination_key: eyJybyI6MS...
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: >-
Data key provided by Predexon. The trading key used by the Order Router
on trade.predexon.com is a separate credential.
````