---
title: "List Alerts"
method: GET
path: "/api/alerts"
tags: ["Alerts"]
---

# List Alerts

`GET /api/alerts`

## 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/alerts`
- Auth: HTTP bearer

## Query parameters

- `type` 'rising_kol' | 'trending_video' | 'audience_drift' | 'comment_keyword', nullable
- `unread` boolean
- `limit` integer

## Headers

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

## Response `200`

Successful Response

- GrowthAlertList
  - `total` integer, required
  - `unread` integer, required
  - `alerts` GrowthAlertOut[], required
    - `id` string, required
    - `alert_type` 'rising_kol' | 'trending_video' | 'audience_drift' | 'comment_keyword', required
    - `subject_username` string, nullable, required
    - `subject_video_id` string, nullable, required
    - `score` number, required
    - `payload` object, nullable, required
    - `is_read` boolean, required
    - `created_at` string, required
    - `reason` string, nullable
    - `trigger` object, nullable
    - `identity` AlertIdentity: KOL identity attached to a rising_kol / trending_video alert so the /alerts feed can render the shared rich KOLCard (avatar + nickname + follower/views/engagement stats) without a per-row follow-up request (Issue #4). ``None`` on the alert when no canonical ``DBAuthor`` row exists for the subject (legacy / never-scraped handle). The stat fields below (``follower_count`` … ``avatar_url_cached``) are additive/optional — back-compat for any caller still reading only the original identity shape — and feed the shared ``KOLCard`` on the web alerts surface so it matches the rest of the app.
      - `username` string, required
      - `display_name` string, nullable
      - `avatar_url` string, nullable
      - `verified` boolean
      - `follower_count` integer, nullable
      - `avg_views` number, nullable
      - `avg_engagement_rate` number, nullable
      - `platform` string, nullable
      - `avatar_url_cached` string, nullable

## 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)