# Realtime Sports API

> Realtime Sports API is a developer API for live scores, play-by-play, box scores, schedules, teams, athletes, injuries, news and betting odds, with push delivery over webhooks and WebSocket, under one schema and one API key. 29 leagues monitored live: NFL, college football, NBA, men's college basketball, MLB, NHL and 23 soccer competitions. 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.

Key facts:
- REST base URL: https://www.realtimesportsapi.com/api/v1 . Auth: `Authorization: Bearer <api key>` (or `X-API-Key`). Free key, no card: https://www.realtimesportsapi.com/signup
- Responses: `{ "success": true, "data": ..., "meta": { "rateLimit": { "limit", "remaining", "reset" } } }`; errors `{ "success": false, "error": { "code", "message" } }`.
- Plans: Free (125 calls/month), Starter $29, Growth $49, Pro $99, Scale $299 per month. HTTP 429 with Retry-After when a limit is hit.
- Not suitable for in-play betting that needs sub-second data. Odds come from a single source book.

## Docs

- [API documentation](https://www.realtimesportsapi.com/docs): REST endpoints, WebSocket and webhooks with examples
- [OpenAPI 3 spec](https://www.realtimesportsapi.com/openapi.json): every endpoint, parameter and response shape
- [Postman collection](https://www.realtimesportsapi.com/postman.json): generated from the spec
- [Interactive reference](https://www.realtimesportsapi.com/api-docs): Swagger UI
- [MCP server](https://www.realtimesportsapi.com/docs/mcp): hosted at https://www.realtimesportsapi.com/api/mcp for Claude, Cursor, ChatGPT
- [Full text for LLMs](https://www.realtimesportsapi.com/llms-full.txt): this file plus every endpoint and plan detail

## Product

- [Pricing](https://www.realtimesportsapi.com/pricing): plans, per-second limits, opt-in overage
- [Schedules](https://www.realtimesportsapi.com/schedules): NFL, college football, NBA and more, with JSON/CSV downloads
- [FAQ](https://www.realtimesportsapi.com/faq)
- [Terms](https://www.realtimesportsapi.com/terms)

## Optional

- [Blog](https://www.realtimesportsapi.com/blog): guides

---

## Overview

Realtime Sports API is a developer API for live scores, play-by-play, box scores, schedules, teams, athletes, injuries, news and betting odds, with push delivery over webhooks and WebSocket, under one schema and one API key.

Coverage: 29 leagues monitored live: NFL, college football, NBA, men's college basketball, MLB, NHL and 23 soccer competitions. Leagues (sport/league slug):
- NFL: football/nfl (schedule by week supported)
- College Football (NCAA FBS): football/college-football (schedule by week supported)
- NBA: basketball/nba
- Men's College Basketball (NCAA): basketball/mens-college-basketball
- MLB: baseball/mlb
- NHL: hockey/nhl
- MLS: soccer/usa.1
- U.S. Open Cup: soccer/usa.open
- English Premier League: soccer/eng.1
- UEFA Champions League: soccer/uefa.champions
- UEFA Europa League: soccer/uefa.europa
- English FA Cup: soccer/eng.fa
- Spanish LaLiga: soccer/esp.1
- Italian Serie A: soccer/ita.1
- Mexican Liga MX: soccer/mex.1
- FIFA World Cup: soccer/fifa.world
- English Women's Super League: soccer/eng.w.1
- UEFA Women's Champions League: soccer/uefa.wchampions
- UEFA Conference League: soccer/uefa.europa.conf
- English League Cup: soccer/eng.league_cup
- German Bundesliga: soccer/ger.1
- French Ligue 1: soccer/fra.1
- NWSL: soccer/usa.nwsl
- English Championship: soccer/eng.2
- FIFA World Cup Qualifying (UEFA): soccer/fifa.worldq.uefa
- FIFA World Cup Qualifying (CONMEBOL): soccer/fifa.worldq.conmebol
- FIFA World Cup Qualifying (AFC): soccer/fifa.worldq.afc
- FIFA World Cup Qualifying (CAF): soccer/fifa.worldq.caf
- FIFA World Cup Qualifying (CONCACAF): soccer/fifa.worldq.concacaf

REST endpoints accept other league slugs from the same source ad hoc, but only the leagues above are monitored live and tested.

Freshness: 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.

## Authentication

Create a free account at https://www.realtimesportsapi.com/signup and copy the API key from the dashboard. Send it on every request as `Authorization: Bearer <api key>`, or as `X-API-Key: <api key>` when a proxy strips the Authorization header. Keys are opaque strings, not JWTs. Missing or unknown keys return HTTP 401 (codes MISSING_TOKEN, USER_NOT_FOUND, TRIAL_EXPIRED).

Example:

```
curl -H "Authorization: Bearer YOUR_API_KEY" https://www.realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/live
```

## Plans and limits

- Free: $0; 125 calls/month (1,000 in the first 30 days); 1 request/s; WebSocket 500 messages/month; no webhooks.
- Starter: $29/month or $290/year; 10,000 calls/month; 5 request/s; WebSocket messages share the monthly pool; webhooks share the monthly pool.
- Growth: $49/month or $490/year; 25,000 calls/month; 10 request/s; WebSocket messages share the monthly pool; webhooks share the monthly pool.
- Pro: $99/month or $990/year; 50,000 calls/month; 20 request/s; WebSocket 100,000 messages/month; webhooks 25,000 deliveries/month.
- Scale: $299/month or $2,990/year; 500,000 calls/month; 100 request/s; WebSocket 500,000 messages/month; webhooks 100,000 deliveries/month.

- Every successful REST call counts as one call. On Starter and Growth, WebSocket messages and webhook deliveries count toward the same monthly pool.
- When the monthly quota is used up: HTTP 429, code RATE_LIMIT_EXCEEDED, with a Retry-After header. Over the per-second rate: HTTP 429, code RATE_LIMIT_PER_SECOND.
- Opt-in overage on paid plans: $2 per 1,000 extra calls, capped by a monthly limit the customer sets (off by default).
- No SLA and no uptime guarantee.

## Push delivery

- Webhooks (paid plans): register an HTTPS URL for event.live, event.score_change, event.status_change, event.play and event.final, optionally filtered by league. Deliveries are signed with HMAC-SHA256 in the X-Webhook-Signature header. Manage them in the dashboard or with the /webhooks endpoints below.
- WebSocket: POST https://www.realtimesportsapi.com/api/websocket/auth with your API key to get a URL and a 1-hour token, connect to url?token=..., then send {"type":"subscribe","event":"event_score_change","filters":{"sport":"football","league":"nfl"}}. Event types: event_score_change, event_live, event_status_change, event_play, event_final, event_odds_change. Free accounts get a 500-message monthly preview.

## MCP server

Hosted Model Context Protocol server at https://www.realtimesportsapi.com/api/mcp (Streamable HTTP, stateless). Same API key (Authorization: Bearer). Each tool call counts as one API call. Setup for Claude Code, Cursor, Claude Desktop and ChatGPT: https://www.realtimesportsapi.com/docs/mcp. Tools:
- list_leagues(): The 29 monitored leagues with the sport/league slugs the other tools take.
- get_live_events(sport, league, include_odds?, detail?): Games in progress now, with score, clock and status.
- get_events(sport, league, limit?, detail?): Current scoreboard: recent, live and upcoming games.
- get_event(sport, league, event_id, include_odds?): Full details for one game.
- get_plays(sport, league, event_id, limit?, page?): Play-by-play, paginated.
- get_box_score(sport, league, event_id): Team totals and player stats.
- get_odds(sport, league, event_id): Current spread, moneyline and total (single source book).
- get_schedule(sport, league, start_date?, end_date?, season?, week?, season_type?, detail?): Games for a date range (up to 31 days) or an NFL/college football week.
- list_teams(sport, league, limit?, page?): Teams in a league.
- get_team(sport, league, team_id): One team: record, standing summary, venue.
- get_team_roster(sport, league, team_id): Current roster grouped by position.
- search_athletes(sport, league, query, limit?): Find players by name.
- get_injuries(sport, league, team_id?): Current injury report.
- get_news(sport, league, team_id?, limit?): Latest league or team headlines.

## REST endpoints (base https://www.realtimesportsapi.com/api/v1)

Path parameters: {sport} is football, basketball, baseball, hockey or soccer; {league} is a league slug from the list above. Full schemas: https://www.realtimesportsapi.com/openapi.json

### Sports

- GET /sports: List sports.
- GET /sports/{sport}/leagues: List leagues for a sport.
- GET /sports/{sport}/leagues/{league}: Get league details. League metadata, current season, and links to related endpoints.

### Events

- GET /sports/{sport}/leagues/{league}/events: List events for a league. Current and upcoming events (the provider's current scoreboard window). For a specific date range or week use the season schedule endpoint. Query: limit, includeOdds.
- GET /sports/{sport}/leagues/{league}/events/live: List live events. Events currently in progress (status.state = "in"). Returns an empty array when nothing is live. For continuous updates prefer webhooks or the WebSocket stream over tight polling. Query: includeOdds.
- GET /sports/{sport}/leagues/{league}/events/{eventId}: Get an event. Query: includeOdds.
- GET /sports/{sport}/leagues/{league}/events/{eventId}/boxscore: Get box score. Team totals and player stats. Supported for basketball, soccer, baseball and football. Football players carry per-category stats (passing, rushing, receiving, defensive, kicking, returns) under `categories`.
- GET /sports/{sport}/leagues/{league}/events/{eventId}/winprobability: Get win probability. Per-play win probability series (join to plays via playId) plus drive summaries, where the source publishes them. Query: drives.
- GET /sports/{sport}/leagues/{league}/events/{eventId}/roster: Get game rosters. Game-specific rosters with per-player flags (starter, didNotPlay, active). Published by the source at kickoff. Query: team, starters, enrich.

### Plays

- GET /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. Query: limit, page, enrich.
- GET /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. Query: enrich.

### Odds

- GET /sports/{sport}/leagues/{league}/events/{eventId}/odds: Get current odds. Current spread, moneyline and total from a single source book. `data` is null (with a `message`) when no odds are available.
- GET /sports/{sport}/leagues/{league}/events/{eventId}/odds/history: Get odds history. Snapshots recorded each time the line changed, newest first. Query: limit.

### Teams

- GET /sports/{sport}/leagues/{league}/teams: List teams. Paginated. College football has 800+ teams across all divisions; for FBS only use the group endpoint (/seasons/{season}/types/2/groups/80/teams). Query: limit, page.
- GET /sports/{sport}/leagues/{league}/teams/{teamId}: Get a team.
- GET /sports/{sport}/leagues/{league}/teams/{teamId}/roster: Get team roster. Current roster grouped by position plus a flat list. Pass `season` for a historical season roster (flat list). Query: season.
- GET /sports/{sport}/leagues/{league}/teams/{teamId}/depthchart: Get depth chart. Query: season.

### Athletes

- GET /sports/{sport}/leagues/{league}/athletes: List athletes. Paginated. Some leagues have tens of thousands of athletes; prefer team rosters or search. Query: limit, page, include.
- GET /sports/{sport}/leagues/{league}/athletes/search: Search athletes by name. Query: query (required), limit.
- GET /sports/{sport}/leagues/{league}/athletes/{athleteId}: Get an athlete. Athlete profile with statistics. Omit season for career/current totals. Query: season, seasonType.
- GET /sports/{sport}/leagues/{league}/athletes/{athleteId}/gamelog: Get athlete game log. Query: season (required), week, seasonType.
- GET /sports/{sport}/leagues/{league}/athletes/{athleteId}/availability-history: Get athlete availability history. Time series of a player's injury/availability designations, newest first, as observed by our snapshots (every 30 minutes). Query: limit, from, to.

### Injuries & Availability

- GET /sports/{sport}/leagues/{league}/injuries: Get injury report. Current injuries grouped by team. Without `team` the league-wide feed is truncated by the source to the 25 most recent records per team; with `team` the complete current report is returned. Empty in the off-season. Query: team.
- GET /sports/{sport}/leagues/{league}/player-availability: Get normalized player availability. One normalized `availability` value per player (OUT, DOUBTFUL, QUESTIONABLE, PROBABLE, DAY_TO_DAY, INJURED_RESERVE, SUSPENDED, AVAILABLE, UNKNOWN). Query: team, status.
- GET /sports/{sport}/leagues/{league}/player-availability/history: Get availability changes feed. League-wide feed of availability designation changes, newest first. Query: team, since, status, limit.

### News

- GET /sports/{sport}/leagues/{league}/news: Get latest news. Rolling window of recent articles from the source. For older articles use /news/history. Query: limit, page, team, athlete, since, from, to.
- GET /sports/{sport}/leagues/{league}/news/history: Get archived news. Our archive of league news, newest first. The archive begins 2026-09-02. Query: from, to, team, athlete, limit, page.

### Transactions

- GET /sports/{sport}/leagues/{league}/transactions: Get transactions. Recent signings, injured-list moves, call-ups, releases and trades. Empty in the off-season. Query: limit, page, team, season.

### Seasons

- GET /sports/{sport}/leagues/{league}/season: Get the active season.
- GET /sports/{sport}/leagues/{league}/seasons: List seasons. Query: limit, page.
- GET /sports/{sport}/leagues/{league}/seasons/{season}: Get a season.
- GET /sports/{sport}/leagues/{league}/seasons/{season}/schedule: Get season schedule. Events for a season, optionally one week (NFL and college football only). With `week`, our synced store (which covers about the next week) is merged with the live scoreboard so future weeks are complete. Without `week`, up to 200 events from the synced store, falling back to the live source. `meta.source` is "synced", "live" or "merged". Query: week, seasonType, includeOdds.
- GET /sports/{sport}/leagues/{league}/seasons/{season}/weeks: List weeks in a season. NFL and college football only. Query: seasonType.
- GET /sports/{sport}/leagues/{league}/seasons/{season}/types: List season types.
- GET /sports/{sport}/leagues/{league}/seasons/{season}/types/{typeId}: Get a season type.
- GET /sports/{sport}/leagues/{league}/seasons/{season}/types/{typeId}/groups: List groups (conferences/divisions).
- GET /sports/{sport}/leagues/{league}/seasons/{season}/types/{typeId}/groups/{groupId}: Get a group.
- GET /sports/{sport}/leagues/{league}/seasons/{season}/types/{typeId}/groups/{groupId}/teams: List teams in a group. Query: pageSize, page.
- GET /sports/{sport}/leagues/{league}/seasons/{season}/teams/{teamId}/events: List a team's events in a season. Query: page, pageSize, limit.
- GET /sports/{sport}/leagues/{league}/seasons/{season}/tournament: Get NCAA tournament games. NCAA tournament games for a season with region, round and First Four flag. Basketball only; excludes NIT/CBI/CIT. Query: round, region, firstFour, startDate, endDate.

### Webhooks

- GET /webhooks: List your webhooks. Requires a paid plan.
- POST /webhooks: Create a webhook. Deliveries are signed with HMAC-SHA256 in the `X-Webhook-Signature` header. The signing secret is returned only in this response (retrieve it later via /webhooks/{webhookId}/secret).
- GET /webhooks/{webhookId}: Get a webhook.
- PATCH /webhooks/{webhookId}: Update a webhook. Partial update of any of url, events, leagues, frequency, active. `active: true` re-enables an automatically deactivated webhook.
- DELETE /webhooks/{webhookId}: Delete a webhook.
- GET /webhooks/{webhookId}/secret: Reveal the signing secret.
- POST /webhooks/{webhookId}/secret: Rotate the signing secret. The old secret stops being used within about one second.
- POST /webhooks/{webhookId}/test: Send a test delivery. Sends a signed sample payload (header `X-Webhook-Test: true`), or replays a recorded failed delivery when `deliveryId` is given.
- GET /webhooks/{webhookId}/deliveries: List failed deliveries. Recent failed delivery attempts. Successful deliveries are not recorded individually. Query: limit.

### WebSocket

- POST https://www.realtimesportsapi.com/api/websocket/auth: Get a WebSocket token. Returns the WebSocket URL and a token valid for one hour. Connect to `${url}?token=${token}`, then send `{"type":"subscribe","event":"event_score_change","filters":{"sport":"football","league":"nfl"}}`. Event types: event_score_change, event_live, event_status_change, event_play, event_final, event_odds_change. Each delivered message counts toward your quota.

## Links

- Docs: https://www.realtimesportsapi.com/docs
- OpenAPI: https://www.realtimesportsapi.com/openapi.json
- Postman: https://www.realtimesportsapi.com/postman.json
- Pricing: https://www.realtimesportsapi.com/pricing
- Support: austin@elcodev.com