---
title: "Get the signed-in fan’s widget snapshot"
method: GET
path: "/api/v1/widgets/snapshot"
tags: ["Engage"]
---

# Get the signed-in fan’s widget snapshot

`GET /api/v1/widgets/snapshot`

## Request

- Base URL: `https://app.d-sports.org`
- URL: `https://app.d-sports.org/api/v1/widgets/snapshot`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Returns personalized Rank / Fan Rep and HQ Live data. Provide a Clerk session (bearer or cookie) or a widget bearer scoped to `widgets:snapshot:read`. Request `?include=clubs` for up to six favorite or followed clubs. If a game in the returned snapshot is live, the private cache max age is 60 seconds; otherwise it is 3600. A weak ETag ignores `updatedAt`; a matching `If-None-Match` returns 304 without a body.

## Query parameters

- `include` string

## Headers

- `If-None-Match` string

## Response `200`

Personalized widget snapshot

- WidgetSnapshotSuccess
  - `success` true, required
  - `data` object, required
    - `rankOrPoints` object, required
      - `fanRep` integer, required: Earned points plus Fan Rep ledger amounts.
      - `rank` integer, nullable, required: Global rank by earned points (not combined Fan Rep), or null when unavailable.
      - `updatedAt` string, date-time, required: Snapshot creation time.
      - `deepLink` '/leaderboard', required
    - `hqLive` object, nullable, required: A live match involving a favorite or followed club, or null if none qualifies.
      - `gameId` string, required
      - `slug` string, nullable, required: Followed club slug for native HQ deep links.
      - `status` 'live', required
      - `home` WidgetTeamSide, required
        - `abbr` string, required
        - `name` string, required
        - `score` integer, nullable, required
        - `logo` string, nullable, required: Raster logo URL (`Team.logoPng`, or non-SVG fallback), or null.
        - `color` string, nullable, required: Team.themeColor, falling back to the first nonblank Team.gradientColors entry, or null.
      - `away` WidgetTeamSide, required
        - `abbr` string, required
        - `name` string, required
        - `score` integer, nullable, required
        - `logo` string, nullable, required: Raster logo URL (`Team.logoPng`, or non-SVG fallback), or null.
        - `color` string, nullable, required: Team.themeColor, falling back to the first nonblank Team.gradientColors entry, or null.
      - `period` string, nullable, required
      - `clock` string, nullable, required
      - `lastPlay` string, nullable, required: Newest play-by-play summary line clamped for widget display.
      - `squadLabel` string, nullable, required: Split-squad label when the club has concurrent squads playing.
      - `deepLink` string, required: Relative web path under /locker-room/game/ (retained for backward compatibility).
      - `appDeepLink` string, required: Native app deep link (`engagenative://hq/match/<gameId>`), with `?slug=<slug>` when a club slug is available.
    - `clubs` WidgetClubSnapshot[]: Present only with `include=clubs`. Up to six favorite or followed clubs, ordered by live games, upcoming games, final games, then clubs without an eligible game.
      - `teamId` string, required
      - `slug` string, required
      - `name` string, required
      - `abbr` string, required
      - `color` string, nullable, required
      - `logo` string, nullable, required
      - `game` object, nullable, required: Best eligible non-demo game: live, soonest upcoming, then latest final; null when none qualifies.
        - `gameId` string, required
        - `status` string, required
        - `startTime` string, date-time, nullable, required
        - `home` WidgetTeamSide, required
          - `abbr` string, required
          - `name` string, required
          - `score` integer, nullable, required
          - `logo` string, nullable, required: Raster logo URL (`Team.logoPng`, or non-SVG fallback), or null.
          - `color` string, nullable, required: Team.themeColor, falling back to the first nonblank Team.gradientColors entry, or null.
        - `away` WidgetTeamSide, required
          - `abbr` string, required
          - `name` string, required
          - `score` integer, nullable, required
          - `logo` string, nullable, required: Raster logo URL (`Team.logoPng`, or non-SVG fallback), or null.
          - `color` string, nullable, required: Team.themeColor, falling back to the first nonblank Team.gradientColors entry, or null.
        - `period` string, nullable, required
        - `clock` string, nullable, required
        - `appDeepLink` string, required: Native app deep link (`engagenative://hq/match/<gameId>?slug=<slug>`).

## Other responses

- `304`: Not Modified (snapshot state unchanged for the supplied `If-None-Match` ETag)
- `401`: UNAUTHORIZED
- `403`: FORBIDDEN (widget token lacks required scope)
- `404`: USER_NOT_PROVISIONED
- `429`: RATE_LIMITED (widget token exceeded 60 req/hr)
- `500`: Unexpected error building the snapshot
- `503`: RATE_LIMITER_UNAVAILABLE (widget-token verification)

## Changes

- **2026-11-21** `63735cf90a04`: 16 info
  - the endpoint scheme security `widgetBearerAuth` was added to the API
  - added the new optional `header` request parameter `If-None-Match`
  - added the new optional `query` request parameter `include`
  - added the non-success response with the status `304`
  - …12 more
- **2026-11-21** `300d0b9a863b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/changes/api/v1/widgets/snapshot/get.md)

---

[API](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api.md) - [All operations](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/llms.txt) - [OpenAPI document](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/revisions/63735cf90a04?raw)
