---
title: "GET /insights/{year}"
method: GET
path: "/insights/{year}"
tags: ["insight"]
---

# GET /insights/{year}

`GET /insights/{year}`

Gets a list of `InsightV2` objects for the given year across all categories. Use year=0 for all-time insights. Returns only global (non-district-scoped) insights.

## Path parameters

- `year` integer, required

## Headers

- `If-None-Match` string

## Response `200`

Successful response

- InsightV2[]
  - union — A typed insight object. Use `category` to discriminate between leaderboard, streak, and timeseries 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', required — What the x-axis represents.
        - `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, or event key).
              - …
            - `y` number, required — Y-axis value.
            - `context` object — Present when point_context_type is match_record.
              - …

## Other responses

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

---

[API](https://skmtc.net/thebluealliance/apis/the-blue-alliance-api-v3.md) · [All operations](https://skmtc.net/thebluealliance/apis/the-blue-alliance-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/thebluealliance/the-blue-alliance-api-v3/revisions/b9b0f447dbcb/schema)