> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therundown.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Teams

> Get team details, rosters, and season statistics

## Overview

The teams endpoints provide team metadata, player rosters, and season-level statistics. Teams are identified by a normalized `teamID` that is consistent across sports and seasons.

***

## Endpoints

<Accordion title="GET /api/v2/teams/{teamID}/ — Get a team by ID">
  Returns team details including name, abbreviation, mascot, and sport association.

  ### Path Parameters

  | Parameter | Description                  |
  | --------- | ---------------------------- |
  | `teamID`  | Normalized team ID (integer) |

  <CodeGroup>
    ```bash cURL theme={null}
    curl "https://therundown.io/api/v2/teams/42/?key=YOUR_API_KEY"
    ```

    ```bash Header Auth theme={null}
    curl -H "X-TheRundown-Key: YOUR_API_KEY" \
      "https://therundown.io/api/v2/teams/42/"
    ```

    ```python Python theme={null}
    import requests

    resp = requests.get(
        "https://therundown.io/api/v2/teams/42/",
        headers={"X-TheRundown-Key": "YOUR_API_KEY"}
    )
    team = resp.json()
    print(f"{team['name']} ({team['abbreviation']})")
    ```

    ```javascript JavaScript theme={null}
    const resp = await fetch(
      "https://therundown.io/api/v2/teams/42/?key=YOUR_API_KEY"
    );
    const team = await resp.json();
    console.log(`${team.name} (${team.abbreviation})`);
    ```
  </CodeGroup>

  ### Example Response

  ```json theme={null}
  {
    "team_id": 42,
    "name": "Boston Celtics",
    "abbreviation": "BOS",
    "mascot": "Celtics",
    "sport_id": 4,
    "conference": "Eastern",
    "division": "Atlantic"
  }
  ```

  <Note>
    If you don't know the team ID, use `GET /api/v2/sports/{sportID}/teams` to list all teams for a sport and find the ID you need.
  </Note>
</Accordion>

<Accordion title="GET /api/v2/teams/{teamID}/players — Get team roster">
  Returns all players currently associated with a team.

  ### Path Parameters

  | Parameter | Description        |
  | --------- | ------------------ |
  | `teamID`  | Normalized team ID |

  <CodeGroup>
    ```bash cURL theme={null}
    curl "https://therundown.io/api/v2/teams/42/players?key=YOUR_API_KEY"
    ```

    ```python Python theme={null}
    import requests

    resp = requests.get(
        "https://therundown.io/api/v2/teams/42/players",
        headers={"X-TheRundown-Key": "YOUR_API_KEY"}
    )
    for player in resp.json()["players"]:
        print(f"{player['name']} - {player['position']}")
    ```

    ```javascript JavaScript theme={null}
    const resp = await fetch(
      "https://therundown.io/api/v2/teams/42/players?key=YOUR_API_KEY"
    );
    const data = await resp.json();
    data.players.forEach(p => console.log(`${p.name} - ${p.position}`));
    ```
  </CodeGroup>

  ### Example Response

  ```json theme={null}
  {
    "players": [
      {
        "player_id": 1002,
        "name": "Jayson Tatum",
        "position": "SF",
        "jersey_number": "0",
        "team_id": 42
      },
      {
        "player_id": 1003,
        "name": "Jaylen Brown",
        "position": "SG",
        "jersey_number": "7",
        "team_id": 42
      },
      {
        "player_id": 1004,
        "name": "Derrick White",
        "position": "PG",
        "jersey_number": "9",
        "team_id": 42
      }
    ]
  }
  ```
</Accordion>

<Accordion title="GET /api/v2/teams/{teamID}/stats — Get team season stats">
  Returns aggregate season statistics for a team.

  ### Parameters

  | Parameter     | Type  | Required | Description                                                                                           |
  | ------------- | ----- | -------- | ----------------------------------------------------------------------------------------------------- |
  | `teamID`      | path  | Yes      | Normalized team ID                                                                                    |
  | `stats_ids`   | query | No       | Comma-separated stat IDs to include (max 12). Use `GET /api/v2/stats` to discover available stat IDs. |
  | `year`        | query | No       | Season year. Defaults to the current season.                                                          |
  | `season_type` | query | No       | Season type ID. Default `2` (regular season). Use `GET /api/v2/season_types` for options.             |

  <CodeGroup>
    ```bash Current season stats theme={null}
    curl "https://therundown.io/api/v2/teams/42/stats?key=YOUR_API_KEY"
    ```

    ```bash Specific stats and year theme={null}
    curl "https://therundown.io/api/v2/teams/42/stats?key=YOUR_API_KEY&stats_ids=1,2,3&year=2025&season_type=2"
    ```

    ```python Python theme={null}
    import requests

    resp = requests.get(
        "https://therundown.io/api/v2/teams/42/stats",
        headers={"X-TheRundown-Key": "YOUR_API_KEY"},
        params={"stats_ids": "1,2,3", "year": 2026}
    )
    for stat in resp.json()[0]["stats"]:
        print(f"{stat['name']}: {stat['value']}")
    ```

    ```javascript JavaScript theme={null}
    const resp = await fetch(
      "https://therundown.io/api/v2/teams/42/stats?key=YOUR_API_KEY&stats_ids=1,2,3&year=2026"
    );
    const data = await resp.json();
    data[0].stats.forEach(s => console.log(`${s.name}: ${s.value}`));
    ```
  </CodeGroup>

  ### Example Response

  ```json theme={null}
  [
    {
      "team": {
        "team_id": 42,
        "name": "Boston Celtics"
      },
      "season": {
        "year": 2026,
        "season_type": "Regular Season"
      },
      "stats": [
        { "stat_id": 1, "name": "Points Per Game", "value": "118.5" },
        { "stat_id": 2, "name": "Rebounds Per Game", "value": "45.2" },
        { "stat_id": 3, "name": "Assists Per Game", "value": "27.8" }
      ]
    }
  ]
  ```
</Accordion>

<Accordion title="GET /api/v2/teams/{teamID}/players/stats — Get player season stats for a team">
  Returns individual player season statistics for all players on a team. Supports filtering by specific players and stat types.

  ### Parameters

  | Parameter     | Type  | Required | Description                                   |
  | ------------- | ----- | -------- | --------------------------------------------- |
  | `teamID`      | path  | Yes      | Normalized team ID                            |
  | `stats_ids`   | query | No       | Comma-separated stat IDs (max 12)             |
  | `player_ids`  | query | No       | Comma-separated player IDs to filter          |
  | `year`        | query | No       | Season year. Defaults to current season.      |
  | `season_type` | query | No       | Season type ID. Default `2` (regular season). |

  <CodeGroup>
    ```bash All player stats for a team theme={null}
    curl "https://therundown.io/api/v2/teams/42/players/stats?key=YOUR_API_KEY"
    ```

    ```bash Specific players and stats theme={null}
    curl "https://therundown.io/api/v2/teams/42/players/stats?key=YOUR_API_KEY&player_ids=100,101&stats_ids=1,2"
    ```

    ```python Python theme={null}
    import requests

    resp = requests.get(
        "https://therundown.io/api/v2/teams/42/players/stats",
        headers={"X-TheRundown-Key": "YOUR_API_KEY"},
        params={"stats_ids": "1,2,3", "year": 2026}
    )

    for player_stat in resp.json():
        print(f"{player_stat['player']['name']}: {player_stat['stats']}")
    ```

    ```javascript JavaScript theme={null}
    const resp = await fetch(
      "https://therundown.io/api/v2/teams/42/players/stats?key=YOUR_API_KEY&stats_ids=1,2,3&year=2026"
    );
    const data = await resp.json();
    data.forEach(p => console.log(`${p.player.name}: ${JSON.stringify(p.stats)}`));
    ```
  </CodeGroup>

  ### Example Response

  ```json theme={null}
  [
    {
      "player": {
        "player_id": 1002,
        "name": "Jayson Tatum",
        "position": "SF"
      },
      "team": {
        "team_id": 42,
        "name": "Boston Celtics"
      },
      "season": {
        "year": 2026,
        "season_type": "Regular Season"
      },
      "stats": [
        { "stat_id": 1, "name": "Points Per Game", "value": "27.4" },
        { "stat_id": 2, "name": "Rebounds Per Game", "value": "8.1" }
      ]
    },
    {
      "player": {
        "player_id": 1003,
        "name": "Jaylen Brown",
        "position": "SG"
      },
      "team": {
        "team_id": 42,
        "name": "Boston Celtics"
      },
      "season": {
        "year": 2026,
        "season_type": "Regular Season"
      },
      "stats": [
        { "stat_id": 1, "name": "Points Per Game", "value": "23.8" },
        { "stat_id": 2, "name": "Rebounds Per Game", "value": "5.5" }
      ]
    }
  ]
  ```
</Accordion>