---
title: "List Watchlist"
method: GET
path: "/api/watchlist"
tags: ["Watchlist"]
---

# List Watchlist

`GET /api/watchlist`

## Request

- Base URL: `https://api.kolens.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kolens.ai/api/watchlist`
- Auth: HTTP bearer

Return the user's watchlist as a single significance-ranked change
digest.

One call yields everything the watchlist UI needs: per-entry identity,
current stats, 7d/30d snapshot deltas, recent activity events, the
"what changed" signal badges, a cached LLM activity summary if present,
and a 0-100 significance score + tier. ``entries`` is sorted by
``significance.score`` descending — the most-changed creator first.

No ``?signals=`` flag any more: the digest IS the response. The
frontend must not fan out to ``GET /api/kols/{username}`` per row.

## Headers

- `x-kolens-user-id` string, nullable
- `x-kolens-workspace-id` string, nullable

## Response `200`

Successful Response

- WatchlistDigestResponse
  - `digest` WatchlistDigestSummary, required: Top-level roll-up — answers "what changed across my watchlist?" in seven integers so the UI can render a header without scanning every entry.
    - `total` integer, required
    - `n_act_now` integer, required
    - `n_notable` integer, required
    - `n_quiet` integer, required
    - `n_new_viral_videos` integer, required
    - `n_newly_dormant` integer, required
    - `total_unseen` integer, required
  - `entries` WatchlistEntryDigest[], required
    - `id` string, required
    - `added_at` string, required
    - `is_paused` boolean, required
    - `platform` string
    - `audience_auto_refresh` boolean
    - `audience_refresh_interval_days` integer
    - `audience_sample_size` integer
    - `audience_last_refreshed_at` string, nullable
    - `identity` IdentityOut, required
      - `username` string, required
      - `display_name` string, nullable
      - `avatar_url` string, nullable
      - `verified` boolean
    - `current` CurrentStatsOut, required
      - `follower_count` integer, nullable
      - `avg_views` number, nullable
      - `avg_engagement_rate` number, nullable
    - `changes` ChangesOut, required
      - `windows` object
      - `recent_events` ActivityEventOut[]
        - `id` string, required
        - `kind` string, required
        - `summary` object, nullable
        - `created_at` string, nullable
        - `seen_at` string, nullable
        - `unseen` boolean
      - `activity_summary` ActivitySummaryOut: The cached LLM ``DBKolActivitySummary`` for this KOL, if one exists.
        - `period` string, required
        - `summary` string, nullable
        - `highlights` string[]
        - `generated_at` string, nullable
    - `signals` SignalOut[]
      - `kind` string, required
      - `severity` string, required
      - `label` string, required
      - `detail` string, nullable
      - `data` object, nullable
    - `latest_video` VideoBriefOut
      - `video_id` string, required
      - `url` string, nullable
      - `thumbnail_url` string, nullable
      - `caption` string, nullable
      - `views` integer, nullable
      - `likes` integer, nullable
      - `created_at` string, nullable
      - `is_sponsored` boolean
      - `is_ad` boolean
    - `days_since_last_post` integer, nullable
    - `outreach` OutreachBriefOut
      - `conversation_id` string, required
      - `status` string, required
      - `last_event_at` string, nullable
      - `days_since_last_event` integer, nullable
      - `event_count` integer
    - `recommendation_score` integer, nullable
    - `significance` SignificanceOut, required
      - `score` integer, required
      - `tier` string, required
      - `reasons` string[]
    - `unseen` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kolens/apis/kolens-api.md) · [All operations](https://skmtc.dev/kolens/apis/kolens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolens/apis/kolens-api/revisions/5d6865ab0a24?raw)