Play-by-play API

Plays for one game in chronological order: text, type, period, clock, score after the play, scoring flags, down-and-distance for football and the athletes involved. Paginated; limit up to 1000 returns a whole game in one call. Data is aggregated from public sources and is typically 20-30 seconds behind live play (about 1 second after our source). There is no SLA.

Paths and parameters

GET/api/v1/sports/{sport}/leagues/{league}/events/{eventId}/plays

Get play-by-play. Plays in chronological order, paginated. Use `limit` up to 1000 to fetch a whole game in one call. On the Free plan this returns 403 LIVE_DATA_REQUIRES_TRIAL while the game is in progress (finished games are free); the free 7-day Starter trial (no card) or a paid plan unlocks it.

  • sport (path, required): Sport slug: football, basketball, baseball, hockey, soccer.
  • league (path, required): League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
  • eventId (path, required): Event (game) id, as returned by the events endpoints.
  • limit (query): Maximum plays to return (default 25, max 1000).
  • page (query): Page number (1-based).
  • enrich (query): Resolve athlete names, teams and positions for play participants (default true). Pass false for faster, id-only results.

GET/api/v1/sports/{sport}/leagues/{league}/events/{eventId}/penalties

Get penalty plays. Only the penalty plays of an event; all plays are scanned, not just one page.

  • sport (path, required): Sport slug: football, basketball, baseball, hockey, soccer.
  • league (path, required): League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
  • eventId (path, required): Event (game) id, as returned by the events endpoints.
  • enrich (query): Resolve athlete names, teams and positions for play participants (default true). Pass false for faster, id-only results.

Live example

Request

curl -H "Authorization: Bearer $RSA_API_KEY" \
  "https://www.realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401873066/plays?limit=3"

Response captured from live data at 2026-11-21 21:00 UTC (refreshed every few minutes). Long arrays are trimmed; meta.rateLimit values are illustrative for a Free key.

Response

{
  "success": true,
  "data": [
    {
      "id": "4018730661",
      "sequenceNumber": "100",
      "text": "GAME",
      "shortText": "Game",
      "alternativeText": "GAME",
      "type": {
        "id": "70",
        "text": "Coin Toss"
      },
      "period": 1,
      "clock": {
        "value": 900,
        "displayValue": "15:00"
      },
      "homeScore": 0,
      "awayScore": 0,
      "scoringPlay": false,
      "scoreValue": 0,
      "situation": {
        "down": 0,
        "distance": 0,
        "yardLine": 0,
        "yardsToEndzone": 0
      },
      "endSituation": {
        "down": 0,
        "distance": 0,
        "yardLine": 0,
        "yardsToEndzone": 65
      },
      "yardsGained": 0,
      "athletes": [],
      "priority": false,
      "modified": "2026-11-20T04:13Z"
    },
    {
      "id": "40187306640",
      "sequenceNumber": "4000",
      "text": "K.Fairbairn kicks 65 yards from HST 35 to IND 0. S.McGowan ran ob at IND 40 for 40 yards (J.Smith). HST-C.Braswell was injured during the play.",
      "shortText": "Ka'imi Fairbairn 65 Yd Kickoff Seth McGowan 40 Yd Kickoff Return",
      "alternativeText": "K.Fairbairn kicks 65 yards from HST 35 to IND 0. S.McGowan ran ob at IND 40 for 40 yards (J.Smith). HST-C.Braswell was injured during the play.",
      "type": {
        "id": "53",
        "text": "Kickoff",
        "abbreviation": "K"
      },
      "period": 1,
      "clock": {
        "value": 900,
        "displayValue": "15:00"
      },
      "wallClock": "2026-11-20T01:15:44Z",
      "homeScore": 0,
      "awayScore": 0,
      "scoringPlay": false,
      "scoreValue": 0,
      "situation": {
        "down": 0,
        "distance": 0,
        "yardLine": 35,
        "yardsToEndzone": 65
      },
      "endSituation": {
        "down": 1,
        "distance": 10,
        "yardLine": 60,
        "yardsToEndzone": 60
      },
      "yardsGained": 40,
      "athletes": [
        {
          "id": "2971573",
          "name": "Ka'imi Fairbairn",
          "displayName": "Ka'imi Fairbairn",
          "shortName": "K. Fairbairn",
          "position": "PK",
          "team": {
            "id": "34"
          },
          "role": "kicker",
          "type": "kicker",
          "order": 1
        },
        {
          "id": "4686468",
          "name": "Seth McGowan",
          "displayName": "Seth McGowan",
          "shortName": "S. McGowan",
          "position": "RB",
          "team": {
            "id": "11"
          },
          "role": "returner",
          "type": "returner",
          "order": 2
        },
        {
          "id": "4594277",
          "name": "Jaylin Smith",
          "displayName": "Jaylin Smith",
          "shortName": "J. Smith",
          "position": "CB",
          "team": {
            "id": "34"
          },
          "role": "tackler",
          "type": "tackler",
          "order": 3
        }
      ],
      "priority": false,
      "modified": "2026-11-20T04:13Z"
    },
    {
      "id": "40187306658",
      "sequenceNumber": "5800",
      "text": "Official Timeout at 14:54.",
      "shortText": "Official Timeout At 14:54. ",
      "alternativeText": "Official Timeout at 14:54.",
      "type": {
        "id": "74",
        "text": "Official Timeout",
        "abbreviation": "Off TO"
      },
      "period": 1,
      "clock": {
        "value": 894,
        "displayValue": "14:54"
      },
      "wallClock": "2026-11-20T01:18:38Z",
      "homeScore": 0,
      "awayScore": 0,
      "scoringPlay": false,
      "scoreValue": 0,
      "situation": {
        "down": 1,
        "distance": 10,
        "yardLine": 60,
        "yardsToEndzone": 0,
        "downDistanceText": "1st & 10 at IND 40",
        "possessionText": "IND 40"
      },
      "endSituation": {
        "down": 1,
        "distance": 10,
        "yardLine": 60,
        "yardsToEndzone": 60
      },
      "yardsGained": 0,
      "athletes": [],
      "priority": false,
      "modified": "2026-11-20T04:13Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 3,
      "total": 160,
      "totalPages": 54,
      "hasNextPage": true,
      "hasPreviousPage": false
    },
    "rateLimit": {
      "limit": 125,
      "remaining": 124,
      "reset": 1796083200000
    }
  }
}

Fields

FieldTypeNotes
idstring
sequenceNumberstring
textstring
shortTextstring
alternativeTextstring
typeobject
periodinteger
clockobject
wallClockstring
homeScoreinteger
awayScoreinteger
scoringPlayboolean
scoreValueinteger
scoringTypestring
situationobject
endSituationobject
yardsGainedinteger
teamIdstring
athletesPlayAthlete[]
priorityboolean
modifiedstring

League support

Checked against live data on 2026-10-04: 29 available, 0 limited, 0 seasonal or not verified, 0 not available.

Available
Available
Men's College Basketball

Verified 2026-11-05 on the first week of games (about 440-520 plays per game).

Available
Available
Available
Available
Available
Available
Available
Available
Available
Available
Available
Available
Available

Code samples

curl

curl -H "Authorization: Bearer $RSA_API_KEY" \
  "https://www.realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401873066/plays?limit=3"

JavaScript (fetch)

const res = await fetch("https://www.realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401873066/plays?limit=3", {
  headers: { Authorization: `Bearer ${process.env.RSA_API_KEY}` }
});
const { success, data, meta } = await res.json();
console.log(data, meta.rateLimit);

Python (requests)

import os, requests

res = requests.get(
    "https://www.realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401873066/plays?limit=3",
    headers={"Authorization": f"Bearer {os.environ['RSA_API_KEY']}"},
    timeout=10,
)
body = res.json()
print(body["data"])

MCP prompt (Claude, Cursor, ChatGPT)

Using the Realtime Sports MCP server (https://www.realtimesportsapi.com/api/mcp), call get_plays with sport "football" and league "nfl" and pick a finished game from get_events and summarize its scoring plays for NFL.

Connect the hosted MCP server first: setup guide. Each tool call counts as one API call.

Each request above is 1 call. Free covers 125 calls a month after a 1,000-call first month, at 1 request/second. Starter is $29/month for 10,000 calls (about 333 a day) plus webhooks and WebSocket, so you stop polling for changes; 7-day free trial. Compare plans

Shipping a product with this data?

Polling works on every plan. Production apps usually also want events pushed to them, by webhook or WebSocket, as soon as we detect them (typically 20-30 seconds behind live play). These guides show the setup and the plan each one needs.

Guides

Rate limits and pricing

PlanPriceCallsRateWebSocketWebhooks
Free$0125/mo (1,000 first 30 days)1/s500 msgs/moNo
Starter$29/mo ($290/yr)10,000/mo5/sShares monthly poolShares monthly pool
Growth$49/mo ($490/yr)25,000/mo10/sShares monthly poolShares monthly pool
Pro$99/mo ($990/yr)50,000/mo20/s100,000 msgs/mo25,000/mo
Business$179/mo ($1,790/yr)150,000/mo40/s300,000 msgs/mo75,000/mo
Scale$299/mo ($2,990/yr)500,000/mo100/s500,000 msgs/mo100,000/mo

Every successful REST call counts as one call. Over the limit you get HTTP 429 with a Retry-After header. No SLA. Full pricing.

FAQ

What does the play-by-play endpoint return?
Plays for one game in chronological order: text, type, period, clock, score after the play, scoring flags, down-and-distance for football and the athletes involved. Paginated; limit up to 1000 returns a whole game in one call.
Which leagues support play-by-play?
All 29 monitored leagues returned data when we checked on 2026-10-04.
Is it free to try?
Yes. The Free plan is $0 with 125 calls per month (1,000 in the first 30 days) at 1 request per second, no card required. Every successful call counts as one call.
How fresh is the data?
Data is aggregated from public sources and is typically 20-30 seconds behind live play (about 1 second after our source). There is no SLA.
Can I get updates pushed instead of polling?
Webhooks are included on every paid plan (Starter, Growth, Pro, Business, Scale). WebSocket is included on paid plans, and the Free plan gets a 500-message monthly preview.