--- title: "GET /insights/{year}/{category}" method: GET path: "/insights/{year}/{category}" tags: ["insight"] --- # GET /insights/{year}/{category} `GET /insights/{year}/{category}` ## Request - Base URL: `https://www.thebluealliance.com/api/v3` - URL: `https://www.thebluealliance.com/api/v3/insights/{year}/{category}` - Auth: API key in header `X-TBA-Auth-Key` Gets a list of `InsightV2` objects for the given year filtered by category. Use year=0 for all-time insights. Returns only global (non-district-scoped) insights. Valid categories: leaderboard, streak, timeseries, game_stats, clubs. ## Path parameters - `year` integer, required - `category` 'leaderboard' | 'streak' | 'timeseries' | 'game_stats' | 'clubs', required ## Headers - `If-None-Match` string ## Response `200` Successful response - InsightV2[] - union: A typed insight object. Use `category` to discriminate between leaderboard, streak, timeseries, game stats, and clubs shapes. - InsightV2Leaderboard - `name` string, required: Programmatic name of the insight, e.g. `blue_banners`. - `display_name` string, required: Human-readable name of the insight, e.g. `Total Blue Banners`. - `year` integer, required: Year the insight was measured in. Use 0 for all-time insights. - `category` 'leaderboard', required: Insight category. Discriminates the shape of `data`. - `district_abbreviation` string, nullable, required: District abbreviation if the insight is district-scoped, otherwise null. - `data` InsightV2LeaderboardData, required: Data for a leaderboard-category InsightV2. Rankings of teams, events, or matches by a numeric value. - `key_type` 'team' | 'event' | 'match' | 'team_pair' | 'alliance', required: What kind of keys appear in the rankings. - `context_type` 'event_list' | 'none' | 'match_alliance', required: Whether rankings include per-entry context. - `rankings` object[], required: Ranked entries, ordered from highest to lowest value. - `keys` union, required: Team/event/match keys sharing this rank. For team_pair, a list of two-element lists. - string[] - array[] - … - `value` number, required: The numeric value for this rank. - `contexts` union[]: Present when context_type is event_list or match_alliance. Parallel to keys. For event_list, each entry lists event_keys. For match_alliance, each entry has match_key and alliance (team keys). - union - … - InsightV2Streak - `name` string, required: Programmatic name of the insight, e.g. `blue_banners`. - `display_name` string, required: Human-readable name of the insight, e.g. `Total Blue Banners`. - `year` integer, required: Year the insight was measured in. Use 0 for all-time insights. - `category` 'streak', required: Insight category. Discriminates the shape of `data`. - `district_abbreviation` string, nullable, required: District abbreviation if the insight is district-scoped, otherwise null. - `data` InsightV2StreakData, required: Data for a streak-category InsightV2. Records of consecutive achievement by teams. - `entries` object[], required - `key` string, required: Team or entity key. - `key_type` 'team' | 'event' | 'match' | 'team_pair', required - `streak_length` integer, required: Length of the streak. - `start` string, required: Event key or year string where the streak began. - `end` string, required: Event key or year string where the streak ended (or is ongoing). - `is_active` boolean, required: Whether this streak is still ongoing. - InsightV2Timeseries - `name` string, required: Programmatic name of the insight, e.g. `blue_banners`. - `display_name` string, required: Human-readable name of the insight, e.g. `Total Blue Banners`. - `year` integer, required: Year the insight was measured in. Use 0 for all-time insights. - `category` 'timeseries', required: Insight category. Discriminates the shape of `data`. - `district_abbreviation` string, nullable, required: District abbreviation if the insight is district-scoped, otherwise null. - `data` InsightV2TimeseriesData, required: Data for a timeseries-category InsightV2. One or more named series of (x, y) data points over time. - `x_type` 'week' | 'year' | 'event' | 'date', required: What the x-axis represents. For `date`, each point's `x` is a Unix timestamp (seconds) at UTC midnight of that day. - `x_label` string, required: Human-readable label for the x-axis. - `y_label` string, required: Human-readable label for the y-axis. - `point_context_type` 'none' | 'match_record', required: Whether data points include additional context. - `series` object[], required - `label` string, required: Human-readable series name. - `points` object[], required - `x` union, required: X-axis value (week string, year integer, event key, or Unix timestamp in seconds when x_type is date). - … - `y` number, required: Y-axis value. - `context` object: Present when point_context_type is match_record. - … - InsightV2GameStats - `name` string, required: Programmatic name of the insight, e.g. `blue_banners`. - `display_name` string, required: Human-readable name of the insight, e.g. `Total Blue Banners`. - `year` integer, required: Year the insight was measured in. Use 0 for all-time insights. - `category` 'game_stats', required: Insight category. Discriminates the shape of `data`. - `district_abbreviation` string, nullable, required: District abbreviation if the insight is district-scoped, otherwise null. - `data` InsightV2GameStatsData, required: Count/opportunities and average-value statistics for a year, broken out by scope: the season overall, each competition week, and each event. - `scopes` InsightV2GameStatsScope[], required - `scope_type` 'overall' | 'week' | 'event', required: What slice of the season this scope covers. - `label` string, required: Display name of the scope, e.g. `Overall`, `Week 3`, or an event's short name. - `key` string, nullable, required: Event key when `scope_type` is `event`, otherwise null. - `week` integer, nullable, required: Zero-indexed competition week, or null for the overall and championship scopes. - `qual` InsightV2GameStat[], required: Count/opportunities statistics over qualification matches in this scope. - `name` string, required: Programmatic name of the statistic, e.g. `rp_1` or `auto_climb`. - `label` string, required: Human-readable name of the statistic, e.g. `Energized RP`. - `count` integer, required: Times the objective was achieved. - `opportunities` integer, required: Chances there were to achieve the objective. - `playoff` InsightV2GameStat[], required: Count/opportunities statistics over playoff matches in this scope. - `name` string, required: Programmatic name of the statistic, e.g. `rp_1` or `auto_climb`. - `label` string, required: Human-readable name of the statistic, e.g. `Energized RP`. - `count` integer, required: Times the objective was achieved. - `opportunities` integer, required: Chances there were to achieve the objective. - `qual_averages` InsightV2AverageStat[], required: Average-value statistics over qualification matches in this scope. - `name` string, required: Programmatic name of the statistic, e.g. `average_score`. - `label` string, required: Human-readable name of the statistic, e.g. `Average Score`. - `value` number, required: The average value of the statistic over matches in this scope. - `playoff_averages` InsightV2AverageStat[], required: Average-value statistics over playoff matches in this scope. - `name` string, required: Programmatic name of the statistic, e.g. `average_score`. - `label` string, required: Human-readable name of the statistic, e.g. `Average Score`. - `value` number, required: The average value of the statistic over matches in this scope. - InsightV2Clubs - `name` string, required: Programmatic name of the insight, e.g. `blue_banners`. - `display_name` string, required: Human-readable name of the insight, e.g. `Total Blue Banners`. - `year` integer, required: Year the insight was measured in. Use 0 for all-time insights. - `category` 'clubs', required: Insight category. Discriminates the shape of `data`. - `district_abbreviation` string, nullable, required: District abbreviation if the insight is district-scoped, otherwise null. - `data` InsightV2ClubsData, required: Data for a clubs-category InsightV2. A cumulative all-time membership of teams that reached a milestone. - `entries` InsightV2ClubEntry[], required: Club members, sorted ascending by team number. - `team_key` string, required: Team key of the club member, e.g. `frc254`. - `event_added_key` string, required: Key of the event where the team first qualified for the club. - `extra_context` InsightV2HallOfFameContext: Chairman's Award material for a Hall of Fame team, scraped from the FIRST resource library. - `year` integer, required: Year the team was inducted (year of `event_added_key`). - `video` string, nullable, required: URL of the team's Chairman's video, or null. - `presentation` string, nullable, required: URL of the team's Chairman's presentation, or null. - `essay` string, nullable, required: URL of the team's Chairman's essay, or null. - `context_type` 'hall_of_fame' | 'none', required: Discriminates the shape of each entry's `extra_context`. `none` means entries have no `extra_context`. ## Other responses - `304`: Not Modified - Use Local Cached Value - `401`: Authorization information is missing or invalid. - `404`: Not Found ## Changes - **2026-09-04** `def03c22de3a`: 1 breaking, 5 warning, 2 info - added `#/components/schemas/InsightV2_Clubs` to the `items/` response property `oneOf` list for the response status `200` - added the new `clubs` enum value to the `items/oneOf[#/components/schemas/InsightV2_GameStats]/allOf[#/components/schemas/InsightV2_Base]/category` response property for the response status `200` - added the new `clubs` enum value to the `items/oneOf[#/components/schemas/InsightV2_Leaderboard]/allOf[#/components/schemas/InsightV2_Base]/category` response property for the response status `200` - added the new `clubs` enum value to the `items/oneOf[#/components/schemas/InsightV2_Streak]/allOf[#/components/schemas/InsightV2_Base]/category` response property for the response status `200` - …4 more - …earlier changes not shown [Operation history](https://skmtc.dev/thebluealliance/apis/the-blue-alliance-api-v3/changes/insights/:year/:category/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)