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.
- Soccer plays are match events (passes, shots, fouls, cards, substitutions), so a full match can have more than 1,000 entries.
- The penalties endpoint scans every play and returns only penalty plays.
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
| Field | Type | Notes |
|---|---|---|
| id | string | |
| sequenceNumber | string | |
| text | string | |
| shortText | string | |
| alternativeText | string | |
| type | object | |
| period | integer | |
| clock | object | |
| wallClock | string | |
| homeScore | integer | |
| awayScore | integer | |
| scoringPlay | boolean | |
| scoreValue | integer | |
| scoringType | string | |
| situation | object | |
| endSituation | object | |
| yardsGained | integer | |
| teamId | string | |
| athletes | PlayAthlete[] | |
| priority | boolean | |
| modified | string |
League support
Checked against live data on 2026-10-04: 29 available, 0 limited, 0 seasonal or not verified, 0 not available.
Verified 2026-11-05 on the first week of games (about 440-520 plays per game).
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.
- Score alerts for your sports app, without pollingWebhooks into your backend, then FCM/APNs · Starter ($29/mo)
- Live scoreboards and game pages for news and media sitesCached REST on your server; optional WebSocket for live ticks · Starter ($29/mo)
- Player stats and box scores for fantasy platformsREST box scores during games, webhooks for finals and plays · Growth ($49/mo)
- Live scores on the screens in your venueFree widget, or one WebSocket feeding every screen · Starter ($29/mo)
- A play-by-play feed for your analytics stackWebSocket for live plays, REST to backfill and reconcile · Growth ($49/mo)
- Stream live scores to your backend over WebSocketWebSocket (server to server) · Starter ($29/mo)
- Sports data for a startup, from prototype to scaleREST, WebSocket and webhooks on one key · Starter ($29/mo)
Guides
Rate limits and pricing
| Plan | Price | Calls | Rate | WebSocket | Webhooks |
|---|---|---|---|---|---|
| Free | $0 | 125/mo (1,000 first 30 days) | 1/s | 500 msgs/mo | No |
| Starter | $29/mo ($290/yr) | 10,000/mo | 5/s | Shares monthly pool | Shares monthly pool |
| Growth | $49/mo ($490/yr) | 25,000/mo | 10/s | Shares monthly pool | Shares monthly pool |
| Pro | $99/mo ($990/yr) | 50,000/mo | 20/s | 100,000 msgs/mo | 25,000/mo |
| Business | $179/mo ($1,790/yr) | 150,000/mo | 40/s | 300,000 msgs/mo | 75,000/mo |
| Scale | $299/mo ($2,990/yr) | 500,000/mo | 100/s | 500,000 msgs/mo | 100,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.