---
title: "GET /team/{team_key}/matches/{year}/simple"
method: GET
path: "/team/{team_key}/matches/{year}/simple"
tags: ["team", "match"]
---

# GET /team/{team_key}/matches/{year}/simple

`GET /team/{team_key}/matches/{year}/simple`

## Request

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

Gets a short-form list of matches for the given team and year.

## Path parameters

- `team_key` string, required
- `year` integer, required

## Headers

- `If-None-Match` string

## Response `200`

Successful response

- MatchSimple[]
  - `key` string, required: TBA match key with the format `yyyy[EVENT_CODE]_[COMP_LEVEL]m[MATCH_NUMBER]`, where `yyyy` is the year, and `EVENT_CODE` is the event code of the event, `COMP_LEVEL` is (pm, qm, ef, qf, sf, f), and `MATCH_NUMBER` is the match number in the competition level. A set number may append the competition level if more than one match in required per set.
  - `comp_level` 'pm' | 'qm' | 'ef' | 'qf' | 'sf' | 'f', required: The competition level the match was played at.
  - `set_number` integer, required: The set number in a series of matches where more than one match is required in the match series.
  - `match_number` integer, required: The match number of the match in the competition level.
  - `alliances` object, required: A list of alliances, the teams on the alliances, and their score.
    - `red` MatchAlliance, required
      - `score` integer, required: Score for this alliance. Will be -1 for an unplayed match.
      - `team_keys` string[], required
      - `surrogate_team_keys` string[], required: TBA team keys (eg `frc254`) of any teams playing as a surrogate.
      - `dq_team_keys` string[], required: TBA team keys (eg `frc254`) of any disqualified teams.
    - `blue` MatchAlliance, required
      - `score` integer, required: Score for this alliance. Will be -1 for an unplayed match.
      - `team_keys` string[], required
      - `surrogate_team_keys` string[], required: TBA team keys (eg `frc254`) of any teams playing as a surrogate.
      - `dq_team_keys` string[], required: TBA team keys (eg `frc254`) of any disqualified teams.
  - `winning_alliance` 'red' | 'blue' | '', required: The color of an alliance, or an empty string when there is no winning alliance (e.g. tie or no result). See https://github.com/the-blue-alliance/the-blue-alliance/blob/main/src/backend/common/consts/alliance_color.py for red/blue definitions.
  - `event_key` string, required: Event key of the event the match was played at.
  - `time` integer, nullable, required: UNIX timestamp (seconds since 1-Jan-1970 00:00:00) of the scheduled match time, as taken from the published schedule.
  - `predicted_time` integer, nullable, required: UNIX timestamp (seconds since 1-Jan-1970 00:00:00) of the TBA predicted match start time.
  - `actual_time` integer, nullable, required: UNIX timestamp (seconds since 1-Jan-1970 00:00:00) of actual match start time.

## Other responses

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

## Changes

- **2026-10-03** `a32ede23975e`: 1 warning
  - added the new `pm` enum value to the `items/comp_level` response property for the response status `200`
- **2026-06-08** `c26cc01880d2`: 1 breaking, 4 info
  - the `items/winning_alliance` response's property type changed from `string` to no type for status `200`
  - added `#/components/schemas/AllianceColor` to the `items/winning_alliance` response property `allOf` list for the response status `200`
  - removed the `` enum value from the `items/winning_alliance` response property for the response status `200`
  - removed the `blue` enum value from the `items/winning_alliance` response property for the response status `200`
  - …1 more
- **2024-09-21** `30390dd088e5`: 3 breaking, 12 info
  - the response property `items/actual_time` became nullable for the status `200`
  - the response property `items/predicted_time` became nullable for the status `200`
  - the response property `items/time` became nullable for the status `200`
  - added the non-success response with the status `404`
  - …11 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`

[Operation history](https://skmtc.dev/thebluealliance/apis/the-blue-alliance-api-v3/changes/team/:team_key/matches/:year/simple/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)