Skip to main content
GET
Get play-by-play for an event

Endpoint details

Returns the play-by-play timeline for a live or completed event — one entry per play with description, period, game clock, running score, and (as attribution rolls out) the players involved. Live game state and play-by-play require an Ultra plan or higher; keys on lower tiers receive a 403. The companion live_game_state snapshot (current inning/quarter, count, base runners, possession, and more) is embedded on live event payloads for entitled keys. Also available for streaming via the plays channel on the V2 WebSocket.

Authorizations

X-TheRundown-Key
string
header
required

Recommended API key request header for new integrations

Path Parameters

eventID
string
required

Canonical V2 event ID from the event_id field returned by event endpoints

Query Parameters

limit
integer
default:50

Number of plays to return. The most recent plays are selected (with after_sequence, the oldest plays after the cursor), then returned in ascending sequence order. Values above 500 are capped.

Required range: x <= 500
before_sequence
integer

Pagination cursor: returns plays with sequence lower than this value. Use the lowest sequence from the previous page to walk backwards through long games. Cannot be combined with after_sequence.

after_sequence
integer

Catch-up cursor: returns plays with sequence higher than this value, oldest first, up to limit. Pass the highest sequence you already have to fetch newer plays; if a page returns limit plays, repeat with the new highest sequence. Cannot be combined with before_sequence (HTTP 400). 0 or a non-numeric value is ignored.

Required range: x >= 1

Response

Play-by-play timeline

event_id
string
sport_id
integer
sport
string
Example:

"mlb"

plays
object[]

Plays in ascending sequence order. Always an array, never null.

latest_sequence
integer

Highest sequence currently available for this event (0 when it has no plays). Present on every response, including empty pages. If your after_sequence cursor is above this value, lower it to this value so polling resumes.

latest_play_id
integer<int64>

play_id of the play at latest_sequence (0 when the event has no plays).