> ## Documentation Index > Fetch the complete documentation index at: https://docs.therundown.io/llms.txt > Use this file to discover all available pages before exploring further. # Get play-by-play for an event > 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. ## OpenAPI ````yaml get /api/v2/events/{eventID}/plays openapi: 3.1.0 info: title: TheRundown Sports API version: 2.0.0 description: > Real-time and historical sports betting data, odds, lines, and statistics across major North American and international sports leagues. ## Authentication All endpoints (except `/sports` and `/affiliates`) require authentication. Pass your API key using one of: - **Query parameter**: `?key=YOUR_API_KEY` - **Header**: `X-Therundown-Key: YOUR_API_KEY` ## Off-the-Board Sentinel Value The value **0.0001** indicates a line is "off the board" — the sportsbook has temporarily removed pricing (e.g., pending injury news). This is NOT an error. Display as "Off Board" or "N/A" in your UI. ## Rate Limiting Requests are rate-limited per API key tier. Check response headers for current limits. ## Data Updates - Live odds update in real-time during games - Use delta endpoints for efficient polling of changes - WebSocket connections available for streaming updates ## V1 vs V2 V2 endpoints use market-based data structures (market_id, participants, line prices). V1 endpoints use legacy line-based structures (moneyline, spread, total objects). V2 is recommended for new integrations. contact: name: TheRundown API Support url: https://therundown.io email: support@therundown.io termsOfService: https://therundown.io/terms servers: - url: https://therundown.io description: Production security: - ApiKeyQuery: [] - ApiKeyHeader: [] tags: - name: V2 Sports description: Sport listings, dates, and teams (V2) - name: V2 Events description: Events with market-based odds (V2) - name: V2 Markets description: Market definitions, odds, deltas, and history (V2) - name: V2 Teams description: Team data, players, and stats (V2) - name: V2 Players description: Player data (V2) - name: V2 Stats description: Team and player statistics (V2) - name: V2 WebSocket description: Real-time streaming via WebSocket (V2) - name: V2 Reference description: Reference data — affiliates, sportsbooks, season types (V2) - name: V1 Events description: Events with line-based odds (V1 legacy) - name: V1 Lines description: Moneyline, spread, total, best-line endpoints (V1 legacy) - name: V1 Sports description: Sport listings, dates, events, schedules (V1 legacy) - name: V1 Delta description: Delta/change feeds (V1 legacy) - name: V1 Reference description: Reference data (V1 legacy) - name: V1 WebSocket description: Real-time streaming via WebSocket (V1 legacy) paths: /api/v2/events/{eventID}/plays: get: tags: - V2 Events summary: Get play-by-play for an event description: > 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. operationId: v2GetPlaysByEvent parameters: - $ref: '#/components/parameters/EventIDPath' - name: limit in: query schema: type: integer default: 50 maximum: 500 description: >- Number of plays to return. The most recent plays are selected, then returned in ascending `sequence` order. Values above 500 are capped. - name: before_sequence in: query schema: type: integer description: >- Pagination cursor — returns plays with `sequence` lower than this value. Use the lowest `sequence` from the previous page to walk backwards through long games. responses: '200': description: Play-by-play timeline content: application/json: schema: $ref: '#/components/schemas/PlaysResponse' example: event_id: 816efd1e5767d7133b5bc70c77173a18 sport_id: 3 sport: mlb plays: - play_id: 88412031 sequence: 214 period: 6 half_indicator: bottom type: single description: Bobby Witt Jr. singles on a line drive to center field. score_away_after: 2 score_home_after: 3 win_probability_home: 0.71 occurred_at: '2026-07-04T01:12:44Z' mlb: batter: player_id: 41123 name: Bobby Witt Jr. team_id: 20 pitch_speed_mph: 94.2 exit_velocity_mph: 102.8 '403': description: The API key's plan does not include live game state content: application/json: example: error: Live game state requires Ultra plan or higher upgrade_url: /pricing/api components: parameters: EventIDPath: name: eventID in: path required: true schema: type: string description: >- Canonical V2 event ID from the `event_id` field returned by event endpoints schemas: PlaysResponse: type: object properties: event_id: type: string sport_id: type: integer sport: type: string example: mlb plays: type: array description: Plays in ascending sequence order. Always an array, never null. items: $ref: '#/components/schemas/Play' Play: type: object properties: play_id: type: integer format: int64 sequence: type: integer description: >- Monotonic ordering key within the event. Use with `before_sequence` to page backwards. team_id: type: integer description: >- Possession/acting team. May be omitted while per-play attribution rolls out. period: type: integer half_indicator: type: string type: type: string description: Play type (e.g. `single`, `strikeout`, `made-three`, `goal`) result: type: string description: type: string example: Bobby Witt Jr. singles on a line drive to center field. scoring_play: type: boolean description: >- Whether this play scored. May be omitted while per-play attribution rolls out. score_value: type: integer description: Points/runs/goals credited by this play score_away_after: type: integer description: Away score after this play score_home_after: type: integer description: Home score after this play win_probability_home: type: number description: Home win probability after this play, 0-1 display_clock: type: string description: Game clock display at the time of the play, where applicable occurred_at: type: string format: date-time participants: type: array description: >- Players involved in the play. May be omitted while per-play attribution rolls out; not available for NFL/NCAAF live plays. items: $ref: '#/components/schemas/PlayParticipant' mlb: type: object description: Baseball-only play details properties: batter: $ref: '#/components/schemas/PlayPlayerSummary' pitcher: $ref: '#/components/schemas/PlayPlayerSummary' scorer: $ref: '#/components/schemas/PlayPlayerSummary' pitch_speed_mph: type: number exit_velocity_mph: type: number hit_distance_ft: type: number launch_angle_deg: type: number football: type: object description: NFL/NCAAF-only play details properties: start_yard_line: type: integer end_yard_line: type: integer stat_yardage: type: integer drive_description: type: string PlayParticipant: type: object properties: player_id: type: integer format: int64 description: Normalized player ID — joins to the players endpoints name: type: string team_id: type: integer role: type: string example: batter position: type: string PlayPlayerSummary: type: object properties: player_id: type: integer format: int64 name: type: string team_id: type: integer securitySchemes: ApiKeyQuery: type: apiKey in: query name: key description: API key as query parameter ApiKeyHeader: type: apiKey in: header name: X-Therundown-Key description: API key as request header ````