---
name: basketballapi
description: Basketball games, scores, box scores, play by play, shot locations, standings and player game logs through the Basketball API (basketballapi.net). Use when an answer needs factual basketball data for a game, team, player or competition.
---

# Basketball API

One REST API and MCP server for basketball data: competitions, seasons, teams, games, box scores, play by play, shots with court positions, standings and player game logs. Operated by DeveloperData.net. All times are UTC.

## When to use it, and when not

- Use it for facts: who played, the score, a player's line, a team's form, a season's table, every shot of a game.
- Box scores, play by play and shots exist where the league records them; schedules and final scores cover many more competitions. Call `list_competitions` (or `GET /v1/competitions`) to see what is held before promising detail.
- It gives no predictions, ratings, tips or betting advice.

## Getting access

- A free key: sign up at https://basketballapi.net/signup (about 30 seconds). Paid plans: https://basketballapi.net/pricing
- Send the key in a header, never in the address: `Authorization: Bearer <key>` or `X-API-Key: <key>`.
- Base address: `https://api.basketballapi.net/v1`
- Ids are short strings with a type prefix, returned by the list calls. Find ids first, then ask for detail.

## The common calls

Games on a day (start here to get game ids):

```
curl -H "Authorization: Bearer $KEY" "https://api.basketballapi.net/v1/games?date=2026-10-05"
```
```json
{"data": [{"id": "...", "competition": {"id": "...", "name": "..."}, "date": "2026-10-05", "tip_off": "2026-10-05T17:00:00Z",
  "status": "final", "home": {"id": "...", "name": "..."}, "away": {"id": "...", "name": "..."}, "home_score": 88, "away_score": 81,
  "has": {"boxscore": true, "playbyplay": true, "shots": false}}]}
```

Yesterday's final scores:

```
curl -H "Authorization: Bearer $KEY" "https://api.basketballapi.net/v1/results/yesterday"
```

One game's box score (every player's line and the team totals):

```
curl -H "Authorization: Bearer $KEY" "https://api.basketballapi.net/v1/games/<game id>/boxscore"
```
```json
{"data": {"game": {"id": "...", "home_score": 88, "away_score": 81},
  "home": {"team": {"id": "...", "name": "..."}, "totals": {"points": 88},
    "players": [{"player": {"id": "...", "name": "..."}, "starter": true, "minutes": "31:12", "points": 18, "rebounds": 6, "assists": 4}]},
  "away": {"team": {"id": "...", "name": "..."}, "totals": {"points": 81}, "players": []}}}
```

Also:

- `GET /v1/games/{id}/playbyplay`: every event in order with the clock and running score.
- `GET /v1/games/{id}/shots`: every shot with its position from the basket and whether it went in.
- `GET /v1/players?q=<3+ letters>` then `GET /v1/players/{id}/games`: find a player, then the game log.
- `GET /v1/standings?competition=<id>`: a season's table from its regular-season results (add `season=<id>` for an earlier one).
- `GET /v1/teams/{id}`: one team with its competitions and seasons, and the club's city, home arena, arena capacity and founding year where known.
- `GET /v1/teams/{id}/form`, `/v1/teams/{id}/head-to-head`, `/v1/players/{id}/splits`, `/v1/stats/leaders`.
- `GET /v1/usage`: your plan, calls used today and the limits (not counted as a call).

The full list, with every parameter and field: https://basketballapi.net/documentation and https://api.basketballapi.net/v1/openapi.json

## MCP server

`https://basketballapi.net/mcp` (streamable HTTP, JSON-RPC over POST), with the same key in the `Authorization: Bearer` header. Tools include `get_games`, `yesterdays_results`, `get_game`, `get_boxscore`, `get_play_by_play`, `get_shots`, `list_competitions`, `find_teams`, `get_team`, `get_standings`, `get_team_form`, `find_players`, `get_player_games`, `get_player_splits` and `get_usage`. Which tools answer depends on the plan. Setup: https://basketballapi.net/mcp

## Limits

- Free key: 10 calls a minute, 100 a day: yesterday's and today's games and results, the competitions and their current season, and usage. Box scores, players, teams and rosters need Live or above.
- Paid plans raise the limits and open the full history and the other endpoints: https://basketballapi.net/pricing
- Lists come in pages of 50 (up to 200 with `per_page`).
- Every answer carries headers saying what is left of the minute and the day.

## Errors

Every error is JSON in one shape:

```json
{"error": {"code": "not_found", "message": "No game with that id.", "docs": "https://basketballapi.net/documentation/errors"}}
```

| HTTP | code | What to do |
|---|---|---|
| 400 | `bad_request` | Fix the request (a key in the address is refused: use a header) |
| 401 | `unauthorized` | Send a valid key |
| 403 | `upgrade_required` | The call or the date is outside the plan |
| 404 | `not_found` | Check the id (ids come from the list calls) |
| 422 | `unknown_parameter` | Remove or rename the parameter |
| 429 | `rate_limited` or `quota_exceeded` | Wait for the minute or the day to roll over |

## A typical workflow

1. Call `list_competitions` (or `GET /v1/competitions`) to find the competition and see what detail it holds.
2. Find the game with `get_games` by date, team or season, and keep its id.
3. Ask for the detail you need: `get_boxscore`, `get_play_by_play` or `get_shots`.
4. For a player, `find_players` by name, then `get_player_games` or `get_player_splits`.
5. On `upgrade_required`, tell the user which plan opens the call; on `rate_limited`, wait and retry once.