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

Changed on Oct 3, 2026

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

Request

Base URL
https://www.thebluealliance.com/api/v3
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/get.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

team_keystring required

TBA Team Key, eg frc254

yearinteger required

Competition Year (or Season). Must be 4 digits.

Headers

If-None-Matchstring

Value of the ETag header in the most recently cached response by the client.

Response

Successful response

keystring 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 be appended to 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_numberinteger required

The set number in a series of matches where more than one match is required in the match series.

match_numberinteger required

The match number of the match in the competition level.

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_keystring required

Event key of the event the match was played at.

timeinteger nullable required

UNIX timestamp (seconds since 1-Jan-1970 00:00:00) of the scheduled match time, as taken from the published schedule.

actual_timeinteger nullable required

UNIX timestamp (seconds since 1-Jan-1970 00:00:00) of actual match start time.

predicted_timeinteger nullable required

UNIX timestamp (seconds since 1-Jan-1970 00:00:00) of the TBA predicted match start time.

post_result_timeinteger nullable required

UNIX timestamp (seconds since 1-Jan-1970 00:00:00) when the match result was posted.

Changes

Oct 3, 2026a32ede23975e Revision changes
- warning
  added the new pm enum value to the / response property for the response status
Jul 26, 20269a7cbeb48787 Revision changes
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer null to number null for status
- breaking
  the /////// response's property type changed from integer null to number null for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status
- breaking
  the /////// response's property type changed from integer to number for status

Operation history (11 revisions)