# NBA API

> NBA provides game scores, standings, player profiles and box scores as a workflow and API.

NBA’s Get scores returns games, scores, start times, TV channels and venues for a date range, optionally filtered by team. Get standings returns conference rankings and team records for a season; Get player returns a player bio and per-game averages by name. Get box score returns game scores, player statistics and points by period for two teams, optionally selected by date.

- Page: https://fous.com/tools/nba
- Handle: `@nba`
- Category: [Sports](https://fous.com/tools/category/sports)
- Source website: https://nba.com
- Last verified: Sep 28, 2026

## Methods

### Get box score

Operation `get_box_score`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get the NBA box score for a game between two teams. Without a date, returns their most recent matchup, including Summer League and games in progress.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `date` | string | no | `"2025-10-21"` | Game date in YYYY-MM-DD, for example 2025-10-21. Defaults to their most recent game. |
| `team_1` | string | yes | `"Rockets"` | First team name, for example Lakers. |
| `team_2` | string | yes | `"Thunder"` | Second team name, for example Warriors. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "team_1",
    "team_2"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Game date in YYYY-MM-DD, for example 2025-10-21. Defaults to their most recent game.",
      "examples": [
        "2025-10-21"
      ]
    },
    "team_1": {
      "type": "string",
      "description": "First team name, for example Lakers.",
      "examples": [
        "Rockets",
        "Lakers"
      ]
    },
    "team_2": {
      "type": "string",
      "description": "Second team name, for example Warriors.",
      "examples": [
        "Thunder",
        "Warriors"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "date": "2025-10-21",
      "team_1": "Rockets",
      "team_2": "Thunder"
    },
    {
      "date": "2025-10-21",
      "team_1": "Lakers",
      "team_2": "Warriors"
    },
    {
      "team_1": "Lakers",
      "team_2": "Warriors"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `date` | string | `"2025-10-21"` |  |
| `arena` | string or null | `"Paycom Center"` |  |
| `score` | string | `"124-125"` |  |
| `status` | string | `"Final/OT2"` |  |
| `team_1` | object |  |  |
| `team_1.name` | string | `"Houston Rockets"` |  |
| `team_1.score` | integer or null | `124` |  |
| `team_1.players` | array |  |  |
| `team_1.points_by_period` | array |  |  |
| `team_2` | object |  |  |
| `team_2.name` | string | `"Oklahoma City Thunder"` |  |
| `team_2.score` | integer or null | `125` |  |
| `team_2.players` | array |  |  |
| `team_2.points_by_period` | array |  |  |
| `game_id` | string | `"0022500001"` |  |
| `game_link` | string | `"https://www.nba.com/game/0022500001/box-score"` |  |

**Example input**

```json
{
  "date": "2025-10-21",
  "team_1": "Rockets",
  "team_2": "Thunder"
}
```

**Example output**

```json
{
  "date": "2025-10-21",
  "arena": "Paycom Center",
  "score": "124-125",
  "status": "Final/OT2",
  "team_1": {
    "name": "Houston Rockets",
    "score": 124,
    "players": [
      {
        "name": "Jabari Smith Jr.",
        "blocks": 0,
        "points": 16,
        "steals": 1,
        "assists": 0,
        "minutes": "41:45",
        "starter": true,
        "rebounds": 5,
        "player_id": 1631095,
        "turnovers": 0,
        "plus_minus": 2,
        "field_goals": "7-15",
        "free_throws": "0-0",
        "three_pointers": "2-6"
      }
    ],
    "points_by_period": [
      {
        "period": "Q1",
        "points": 30
      }
    ]
  },
  "team_2": {
    "name": "Oklahoma City Thunder",
    "score": 125,
    "players": [
      {
        "name": "Luguentz Dort",
        "blocks": 0,
        "points": 6,
        "steals": 1,
        "assists": 5,
        "minutes": "45:15",
        "starter": true,
        "rebounds": 6,
        "player_id": 1629652,
        "turnovers": 1,
        "plus_minus": 2,
        "field_goals": "2-12",
        "free_throws": "2-2",
        "three_pointers": "0-8"
      }
    ],
    "points_by_period": [
      {
        "period": "Q1",
        "points": 27
      }
    ]
  },
  "game_id": "0022500001",
  "game_link": "https://www.nba.com/game/0022500001/box-score"
}
```

### Get player

Operation `get_player`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get an NBA player’s bio and regular-season per-game averages by name, including retired players. Season averages are unavailable when the player has no current reported season.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `player` | string | yes | `"Michael Jordan"` | NBA player name, such as Stephen Curry. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "player"
  ],
  "properties": {
    "player": {
      "type": "string",
      "description": "NBA player name, such as Stephen Curry.",
      "examples": [
        "Michael Jordan",
        "Stephen Curry",
        "Darius Acuff Jr."
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "player": "Michael Jordan"
    },
    {
      "player": "Stephen Curry"
    },
    {
      "player": "Darius Acuff Jr."
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `age` | integer or null | `63` | Age in years. |
| `name` | string or null | `"Michael Jordan"` | Player’s full name. |
| `team` | string or null | `"Chicago Bulls"` | Team shown on the NBA player profile. |
| `draft` | string or null | `"1984 Round 1, Pick 3"` | Draft year, round and overall pick. |
| `height` | string or null | `"6 ft 6 in"` | Height in feet and inches. |
| `season` | string or null | `"2025-26"` | Season associated with the season averages, such as 2025-26. |
| `country` | string or null | `"USA"` | Country. |
| `position` | string or null | `"Guard"` | Playing position. |
| `height_cm` | number or null | `198.1` | Height in centimeters. |
| `player_url` | string or null | `"https://www.nba.com/player/893/michael-jordan"` | NBA player page link. |
| `date_of_birth` | string or null | `"1963-02-17"` | Birth date in YYYY-MM-DD format. |
| `jersey_number` | string or null | `"23"` | Jersey number, preserving leading zeros. |
| `nba_player_id` | integer | `893` | NBA player identifier. |
| `weight_pounds` | integer or null | `216` | Weight in pounds. |
| `career_averages` | any |  | Career regular-season per-game averages, or null if unavailable. |
| `season_averages` | any |  | Regular-season per-game averages for the reported season, or null if unavailable. |
| `years_in_league` | integer or null | `15` | NBA seasons of experience. |
| `headshot_image_url` | string or null | `"https://cdn.nba.com/headshots/nba/latest/1040x760/893.png"` | NBA headshot image link. |
| `college_or_last_club` | string or null | `"North Carolina"` | College or last club. |

**Example input**

```json
{
  "player": "Michael Jordan"
}
```

**Example output**

```json
{
  "age": 63,
  "name": "Michael Jordan",
  "team": "Chicago Bulls",
  "draft": "1984 Round 1, Pick 3",
  "height": "6 ft 6 in",
  "season": null,
  "country": "USA",
  "position": "Guard",
  "height_cm": 198.1,
  "player_url": "https://www.nba.com/player/893/michael-jordan",
  "date_of_birth": "1963-02-17",
  "jersey_number": "23",
  "nba_player_id": 893,
  "weight_pounds": 216,
  "career_averages": {
    "blocks": 0.8,
    "points": 30.1,
    "steals": 2.3,
    "assists": 5.3,
    "minutes": 38.3,
    "rebounds": 6.2,
    "games_played": 1072,
    "field_goal_percentage": 49.7,
    "free_throw_percentage": 83.5,
    "three_point_percentage": 32.7
  },
  "season_averages": null,
  "years_in_league": 15,
  "headshot_image_url": "https://cdn.nba.com/headshots/nba/latest/1040x760/893.png",
  "college_or_last_club": "North Carolina"
}
```

### Get scores

Operation `get_scores`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get NBA games, scores, start times, TV channels and venues for a date or up to seven days. Dates follow the NBA games calendar in US Eastern time.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `date` | string | no | `"2026-10-03"` | First NBA calendar date, for example 2026-10-03. Defaults to today in US Eastern time. |
| `days` | integer | no | `2` | Number of calendar days to include, for example 7 (one week). |
| `team` | string | no | `"Celtics"` | Keep only this team’s games, for example Boston Celtics or Celtics. |
| `time_zone` | string | no | `"America/Los_Angeles"` | Time zone for game start times, for example America/Los_Angeles. Defaults to US Eastern. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "First NBA calendar date, for example 2026-10-03. Defaults to today in US Eastern time.",
      "examples": [
        "2026-10-03",
        "2025-04-01",
        "2026-09-28"
      ]
    },
    "days": {
      "type": "integer",
      "default": 1,
      "maximum": 7,
      "minimum": 1,
      "description": "Number of calendar days to include, for example 7 (one week).",
      "examples": [
        2,
        7
      ]
    },
    "team": {
      "type": "string",
      "description": "Keep only this team’s games, for example Boston Celtics or Celtics.",
      "examples": [
        "Celtics"
      ]
    },
    "time_zone": {
      "type": "string",
      "default": "America/New_York",
      "description": "Time zone for game start times, for example America/Los_Angeles. Defaults to US Eastern.",
      "examples": [
        "America/Los_Angeles"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "date": "2026-10-03"
    },
    {
      "date": "2025-04-01",
      "days": 2,
      "team": "Celtics",
      "time_zone": "America/Los_Angeles"
    },
    {
      "date": "2025-04-01",
      "days": 2
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `games` | array |  |  |
| `games[].city` | string or null | `"Quebec City"` |  |
| `games[].date` | string | `"2026-10-03"` | NBA calendar date of the game. |
| `games[].arena` | string or null | `"Videotron Centre"` |  |
| `games[].clock` | string or null |  | Game clock when live. |
| `games[].status` | string | `"scheduled"` |  |
| `games[].game_id` | string | `"0012600009"` |  |
| `games[].quarter` | string or null |  | Current quarter or overtime when live. |
| `games[].away_team` | string | `"Miami Heat"` |  |
| `games[].game_link` | string | `"https://www.nba.com/game/mia-vs-tor-0012600009"` |  |
| `games[].home_team` | string | `"Toronto Raptors"` |  |
| `games[].away_score` | integer or null | `124` |  |
| `games[].home_score` | integer or null | `103` |  |
| `games[].start_time` | string or null | `"2026-10-03T19:00:00-04:00"` | Scheduled start in the requested time zone, or null if not announced. |
| `games[].tv_channels` | array |  | TV broadcasters listed on the game card. |

**Example input**

```json
{
  "date": "2026-10-03"
}
```

**Example output**

```json
{
  "games": [
    {
      "city": "Quebec City",
      "date": "2026-10-03",
      "arena": "Videotron Centre",
      "clock": null,
      "status": "scheduled",
      "game_id": "0012600009",
      "quarter": null,
      "away_team": "Miami Heat",
      "game_link": "https://www.nba.com/game/mia-vs-tor-0012600009",
      "home_team": "Toronto Raptors",
      "away_score": null,
      "home_score": null,
      "start_time": "2026-10-03T19:00:00-04:00",
      "tv_channels": [
        "NBA TV"
      ]
    }
  ]
}
```

### Get standings

Operation `get_standings`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get NBA regular-season standings in Eastern and Western Conference rank order for a season. Defaults to the season shown on NBA standings.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `season` | string | no | `"2024-25"` | NBA season, such as "2025-26" or its starting year "2025". Defaults to the season displayed on the NBA standings page. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "season": {
      "type": "string",
      "default": "",
      "description": "NBA season, such as \"2025-26\" or its starting year \"2025\". Defaults to the season displayed on the NBA standings page.",
      "examples": [
        "2024-25",
        "2025"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {},
    {
      "season": "2024-25"
    },
    {
      "season": "2025"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `season` | string | `"2025-26"` | Season shown in the standings. |
| `eastern_conference` | array |  | Eastern Conference teams in rank order. |
| `eastern_conference[].rank` | integer | `1` | Team position in the conference. |
| `eastern_conference[].team` | string | `"Detroit Pistons"` | Team name. |
| `eastern_conference[].wins` | integer | `60` | Games won. |
| `eastern_conference[].losses` | integer | `22` | Games lost. |
| `eastern_conference[].streak` | string or null | `"Won 3"` | Current consecutive wins or losses. |
| `eastern_conference[].last_10` | string or null | `"8-2"` | Record in the last ten games. |
| `eastern_conference[].page_url` | string | `"https://www.nba.com/team/1610612765/pistons"` | NBA team page. |
| `eastern_conference[].away_record` | string or null | `"28-13"` | Away wins and losses. |
| `eastern_conference[].home_record` | string or null | `"31-9"` | Home wins and losses. |
| `eastern_conference[].games_behind` | number or null | `0` | Games behind the conference leader. |
| `eastern_conference[].clinch_status` | string or null | `"Clinched Eastern Conference"` | Clinch or elimination status when shown. |
| `eastern_conference[].win_percentage` | number | `0.732` | Fraction of games won. |
| `western_conference` | array |  | Western Conference teams in rank order. |
| `western_conference[].rank` | integer | `1` | Team position in the conference. |
| `western_conference[].team` | string | `"Oklahoma City Thunder"` | Team name. |
| `western_conference[].wins` | integer | `64` | Games won. |
| `western_conference[].losses` | integer | `18` | Games lost. |
| `western_conference[].streak` | string or null | `"Lost 2"` | Current consecutive wins or losses. |
| `western_conference[].last_10` | string or null | `"7-3"` | Record in the last ten games. |
| `western_conference[].page_url` | string | `"https://www.nba.com/team/1610612760/thunder"` | NBA team page. |
| `western_conference[].away_record` | string or null | `"30-10"` | Away wins and losses. |
| `western_conference[].home_record` | string or null | `"34-7"` | Home wins and losses. |
| `western_conference[].games_behind` | number or null | `0` | Games behind the conference leader. |
| `western_conference[].clinch_status` | string or null | `"Clinched Western Conference"` | Clinch or elimination status when shown. |
| `western_conference[].win_percentage` | number | `0.78` | Fraction of games won. |

**Example input**

```json
{}
```

**Example output**

```json
{
  "season": "2025-26",
  "eastern_conference": [
    {
      "rank": 1,
      "team": "Detroit Pistons",
      "wins": 60,
      "losses": 22,
      "streak": "Won 3",
      "last_10": "8-2",
      "page_url": "https://www.nba.com/team/1610612765/pistons",
      "away_record": "28-13",
      "home_record": "31-9",
      "games_behind": 0,
      "clinch_status": "Clinched Eastern Conference",
      "win_percentage": 0.732
    },
    {
      "rank": 2,
      "team": "Boston Celtics",
      "wins": 56,
      "losses": 26,
      "streak": "Won 2",
      "last_10": "8-2",
      "page_url": "https://www.nba.com/team/1610612738/celtics",
      "away_record": "26-15",
      "home_record": "30-11",
      "games_behind": 4,
      "clinch_status": "Clinched Atlantic Division",
      "win_percentage": 0.683
    }
  ],
  "western_conference": [
    {
      "rank": 1,
      "team": "Oklahoma City Thunder",
      "wins": 64,
      "losses": 18,
      "streak": "Lost 2",
      "last_10": "7-3",
      "page_url": "https://www.nba.com/team/1610612760/thunder",
      "away_record": "30-10",
      "home_record": "34-7",
      "games_behind": 0,
      "clinch_status": "Clinched Western Conference",
      "win_percentage": 0.78
    },
    {
      "rank": 2,
      "team": "San Antonio Spurs",
      "wins": 62,
      "losses": 20,
      "streak": "Lost 1",
      "last_10": "8-2",
      "page_url": "https://www.nba.com/team/1610612759/spurs",
      "away_record": "29-12",
      "home_record": "32-8",
      "games_behind": 2,
      "clinch_status": "Clinched Southwest Division",
      "win_percentage": 0.756
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@nba",
  "visibility": "public",
  "operation": "get_box_score",
  "version": 1,
  "input": {
    "date": "2025-10-21",
    "team_1": "Rockets",
    "team_2": "Thunder"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@nba\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_box_score\",\n  \"version\": 1,\n  \"input\": {\n    \"date\": \"2025-10-21\",\n    \"team_1\": \"Rockets\",\n    \"team_2\": \"Thunder\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@nba",
  "visibility": "public",
  "operation": "get_box_score",
  "version": 1,
  "input": {
    "date": "2025-10-21",
    "team_1": "Rockets",
    "team_2": "Thunder"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/nba`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_box_score`: Get box score. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_player`: Get player. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_scores`: Get scores. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_standings`: Get standings. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-nba https://api.fous.com/mcp/tools/nba --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Track game scores and start times by team.
- Compare conference standings across seasons.
- Review a player’s bio and regular-season averages.
- Analyze player statistics and scoring by period in a matchup.

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this NBA tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a NBA account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from nba.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 28, 2026.

### What are the scores for a date or team?

Get scores returns games and scores for a date or date range, with an optional team filter.

### Which teams lead each conference?

Get standings returns Eastern and Western Conference teams in rank order for a season.

### What did players record in a matchup?

Get box score returns player statistics and points by period for two teams.

## Related

- [ESPN API](https://fous.com/tools/espn.md): ESPN provides daily scores and schedules, team results, player statistics, matchup summaries, and latest topic-specific headlines; coverage and published details vary, especially for college and soccer.
- [NHL API](https://fous.com/tools/nhl.md): NHL provides games, schedules, and scores when published, standings by date, and player profiles with regular-season stats; dates outside a season have no teams, and unavailable stats are null.
- [Yahoo Sports API](https://fous.com/tools/yahoo-sports.md): Yahoo Sports returns date-based scores and schedules, seasonal standings, and player regular-season and career stats when Yahoo provides them; unavailable data may be missing.
- [MLB API](https://fous.com/tools/mlb.md): MLB provides scores, schedules and game details for one date or up to seven days, regular-season division standings defaulting to the current year, and player profiles with regular-season stats for a selected season and career.
- [NFL API](https://fous.com/tools/nfl.md): NFL provides weekly scores and schedules, regular-season standings, current rosters, and player season and career stats; released players are excluded, and ages or stats may be unavailable.
- [NCAA API](https://fous.com/tools/ncaa.md): NCAA provides college sports scores and schedules from NCAA.com, including date-based games or football weeks, plus latest NCAA.com Top 25 rankings where published.
- [Sports Reference API](https://fous.com/tools/sports-reference.md): Sports Reference provides regular-season career stats, awards and season records across basketball, football, baseball and hockey, plus season leaders using the latest published season if unspecified.
- [Premier League API](https://fous.com/tools/premier-league.md): Premier League provides current/chosen-season tables and recent form, date-range fixtures/results (up to 380), player profiles and stats, and seasonal leaders; older-season stats may be limited.
- [All Sports tools](https://fous.com/tools/category/sports)