---
title: "GET /teams/{year}/{page_num}"
method: GET
path: "/teams/{year}/{page_num}"
tags: ["team"]
---

# GET /teams/{year}/{page_num}

`GET /teams/{year}/{page_num}`

## Request

- Base URL: `https://www.thebluealliance.com/api/v3`
- URL: `https://www.thebluealliance.com/api/v3/teams/{year}/{page_num}`
- Auth: API key in header `X-TBA-Auth-Key`
- TypeScript: <https://skmtc.dev/thebluealliance/apis/the-blue-alliance-api-v3/docs/teams/:year/:page_num/get.ts> (a function with typed inputs; its response is checked against the schema)

Gets a list of `Team` objects that competed in the given year, paginated in groups of 500.

## Path parameters

- `year` integer, required
- `page_num` integer, required

## Headers

- `If-None-Match` string

## Response `200`

Successful response

- Team[]
  - `key` string, required: TBA team key with the format `frcXXXX` with `XXXX` representing the team number.
  - `team_number` integer, required: Official team number issued by FIRST.
  - `nickname` string, required: Team nickname provided by FIRST.
  - `name` string, required: Official long name registered with FIRST.
  - `school_name` string, nullable, required: Name of team school or affilited group registered with FIRST.
  - `city` string, nullable, required: City of team derived from parsing the address registered with FIRST.
  - `state_prov` string, nullable, required: State of team derived from parsing the address registered with FIRST.
  - `country` string, nullable, required: Country of team derived from parsing the address registered with FIRST.
  - `address` string, nullable, required: Always null. Teams are not geocoded, so there is no address or location name; use city, state_prov, country, and postal_code.
  - `postal_code` string, nullable, required: Postal code from the team address.
  - `gmaps_place_id` string, nullable, required: Will be NULL, for future development.
  - `gmaps_url` string, url, nullable, required: Will be NULL, for future development.
  - `lat` number, double, nullable, required: Will be NULL, for future development.
  - `lng` number, double, nullable, required: Will be NULL, for future development.
  - `location_name` string, nullable, required: Always null. Teams are not geocoded, so there is no address or location name; use city, state_prov, country, and postal_code.
  - `website` string, url, nullable, required: Official website associated with the team.
  - `rookie_year` integer, nullable, required: First year the team officially competed.
  - `motto` string, nullable, required: Team's motto or tagline.

## Other responses

- `304`: Not Modified - Use Local Cached Value
- `401`: Authorization information is missing or invalid.
- `404`: Not Found

## Changes

- **2026-02-08** `cc960731dc5b`: 3 info
  - api tag `list` removed
  - the response property `items/website` became required for the status `200`
  - added the required property `items/motto` to the response with the `200` status
- **2024-09-21** `30390dd088e5`: 13 breaking, 2 warning, 14 info
  - the response property `items/address` became nullable for the status `200`
  - the response property `items/city` became nullable for the status `200`
  - the response property `items/country` became nullable for the status `200`
  - the response property `items/gmaps_place_id` became nullable for the status `200`
  - …25 more
- **2024-03-29** `7bf03129c828`: 1 info
  - added the media type `application/json` for the response with the status `401`
- **2022-11-18** `5b245377faaf`: 2 warning, 1 info
  - the optional response header `Last-Modified` removed for the status `200`
  - deleted the `header` request parameter `If-Modified-Since`
  - added the new optional `header` request parameter `If-None-Match`
- **2020-03-06** `a78c0ff8885f`: 1 info
  - added the media type `application/json` for the response with the status `200`

[Operation history](https://skmtc.dev/thebluealliance/apis/the-blue-alliance-api-v3/changes/teams/:year/:page_num/get.md)

---

[API](https://skmtc.dev/thebluealliance/apis/the-blue-alliance-api-v3.md) - [All operations](https://skmtc.dev/thebluealliance/apis/the-blue-alliance-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/thebluealliance/apis/the-blue-alliance-api-v3/revisions/9316d02dee32?raw)