# 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/workflows/nba
- Handle: `@nba`
- Category: [Sports](https://fous.com/workflows/category/sports)
- Source website: https://nba.com
- Last verified: Sep 28, 2026
- Fous is not affiliated with NBA.

## Methods

### Get box score

Operation `get_box_score`, version 1. 1 credit per call.

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 call.

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 call.

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 call.

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 |  | Season shown in the standings. |
| `eastern_conference` | array |  | Eastern Conference teams in rank order. |
| `eastern_conference[].rank` | integer |  | Team position in the conference. |
| `eastern_conference[].team` | string |  | Team name. |
| `eastern_conference[].wins` | integer |  | Games won. |
| `eastern_conference[].losses` | integer |  | Games lost. |
| `eastern_conference[].streak` | string or null |  | Current consecutive wins or losses. |
| `eastern_conference[].last_10` | string or null |  | Record in the last ten games. |
| `eastern_conference[].page_url` | string |  | NBA team page. |
| `eastern_conference[].away_record` | string or null |  | Away wins and losses. |
| `eastern_conference[].home_record` | string or null |  | Home wins and losses. |
| `eastern_conference[].games_behind` | number or null |  | Games behind the conference leader. |
| `eastern_conference[].clinch_status` | string or null |  | Clinch or elimination status when shown. |
| `eastern_conference[].win_percentage` | number |  | Fraction of games won. |
| `western_conference` | array |  | Western Conference teams in rank order. |
| `western_conference[].rank` | integer |  | Team position in the conference. |
| `western_conference[].team` | string |  | Team name. |
| `western_conference[].wins` | integer |  | Games won. |
| `western_conference[].losses` | integer |  | Games lost. |
| `western_conference[].streak` | string or null |  | Current consecutive wins or losses. |
| `western_conference[].last_10` | string or null |  | Record in the last ten games. |
| `western_conference[].page_url` | string |  | NBA team page. |
| `western_conference[].away_record` | string or null |  | Away wins and losses. |
| `western_conference[].home_record` | string or null |  | Home wins and losses. |
| `western_conference[].games_behind` | number or null |  | Games behind the conference leader. |
| `western_conference[].clinch_status` | string or null |  | Clinch or elimination status when shown. |
| `western_conference[].win_percentage` | number |  | Fraction of games won. |

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_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.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

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=120) 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.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_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);
```

Or describe the data in plain language: send `{"api":"@nba","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## 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

### Is Fous affiliated with NBA?

No. Fous is not affiliated with NBA. This workflow reads the public nba.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. 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; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check 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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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 workflows](https://fous.com/workflows/category/sports)