Developers

NBA Data REST API

Read-only access to teams, players, schedules, scores, games, and player box scores.

Authentication

API data is provided for personal, non-commercial entertainment only and is not financial or betting advice. Use is subject to the Terms and Conditions.

Create one API token from your profile. Send it in the HTTP Authorization header. Tokens are shown once and cannot be recovered; rotate or delete a token from your profile if it is exposed.

New tokens begin with nbastat_. Existing tokens that begin with nba_live_ remain valid.

curl "https://nbastat.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Tokens do not expire automatically. Never place a token in a URL, browser source code, repository, log, or public message.

Rate limits

The default limit is 10 authenticated requests in any rolling 60-minute window. The limit will be increased in the future depending on server capacity. Rotating a token does not reset the account limit.

Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A limited response uses HTTP 429 and includes Retry-After.

Endpoints

All id values, detail route parameters, team_id filters, and relationship fields are NBA Stat internal IDs. They are stable API identifiers but are not NBA feed identifiers. Scraped NBA identifiers are not exposed as entity IDs.

GET /api/v1/teams

Return all 30 NBA teams, ordered by full team name. This endpoint has no query parameters or pagination.

GET /api/v1/teams/{team_id}

Retrieve one NBA team by its numeric NBA Stat internal ID.

team_id required path integer: The internal id returned by a team list or relationship field.

GET /api/v1/players

List players, with optional name and team filters.

q optional string: Search part of a player’s name, display name, first name, or last name. Maximum 100 characters.
team_id optional integer: Return players currently assigned to this NBA Stat internal team ID.
page optional integer: Results page to return. Must be 1 or greater; defaults to 1.
per_page optional integer: Records per page, from 1 to 100; defaults to 25.

Example: /api/v1/players?q=James&team_id=12&page=1

GET /api/v1/players/{player_id}

Retrieve one player by numeric NBA Stat internal ID.

player_id required path integer: The internal id returned by a player list or relationship field.

GET /api/v1/games

List schedules and scores, ordered by scheduled tip-off time.

date_from optional date: Include games on or after this game date, formatted YYYY-MM-DD.
date_to optional date: Include games on or before this game date, formatted YYYY-MM-DD. It cannot be earlier than date_from.
team_id optional integer: Return games where this internal team ID is either the home or away team.
status optional enum: One of Final, In Progress, Not Started, Scheduled, or Postponed. Values are case-sensitive.
season optional string: Season label in YYYY-YY format, such as 2026-27.
order optional enum: Tip-off sort direction: asc or desc; defaults to asc.
page optional integer: Results page to return. Must be 1 or greater; defaults to 1.
per_page optional integer: Records per page, from 1 to 100; defaults to 25.

Example: /api/v1/games?date_from=2026-10-10&date_to=2026-10-17&status=Scheduled&order=asc

GET /api/v1/games/{game_id}

Retrieve one scheduled or completed game by its numeric NBA Stat internal ID.

game_id required path integer: The internal id returned by a game list or relationship field.

GET /api/v1/games/{game_id}/boxscore

Retrieve game details and player box-score statistics using the game’s internal ID. Scheduled games may return an empty players array.

game_id required path integer: The internal id of the game whose player box score should be returned.

Pagination and responses

The player and game collection endpoints default to 25 records. Set per_page from 1 to 100 and use page to move through results. The teams endpoint always returns all 30 teams and does not include pagination metadata.

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 30,
    "total_pages": 2
  },
  "request_id": "00000000-0000-4000-8000-000000000000"
}

Errors

Errors use standard HTTP status codes: 401 for authentication, 404 for missing resources, 405 for unsupported methods, 422 for invalid parameters, and 429 for rate limits.

{
  "error": {
    "code": "invalid_parameter",
    "message": "date_from must use the YYYY-MM-DD format."
  },
  "request_id": "00000000-0000-4000-8000-000000000000"
}