# Alerts

Create and manage outlier alerts on saved channels.

Set up growth alerts on channels, folders, and saved searches. Alerts fire once a night and show once the next morning. Plan limits: Starter 3, Professional 25, Ultimate unlimited.

### `list_alerts`

List all the user's active alerts (paused and unpaused). No parameters required.

**Example prompt**

"What alerts do I have?"

### `create_alert`

Create a growth alert. Fires once a night when the threshold is crossed. Three target types: **channel** (single channel), **folder** (any channel in a folder), **search** (new channels matching a saved search).

**Example prompt**

"Alert me when any channel in my Cooking Research folder gains 5000+ subs in 24 hours"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| target_type | string | required | What the alert watches: `channel` (single channel), `folder` (any channel in a folder), or `search` (new channels matching a saved search). |
| target_value | object | required | Shape depends on target_type: `{"channel_id": "UCxxx..."}` for channel, `{"folder_id": 47}` for folder, `{"query": {"q": "cooking", "max_subs": 100000, "content_type": "shorts"}}` for search. |
| conditions | array | null | Array of {metric, threshold} pairs. ALL conditions must pass (AND logic) for the alert to fire. Use this for compound alerts like 'avg_duration >= 3600 AND views_24h >= 1000'. Each dict needs 'metric' (string) and 'threshold' (number — float accepted for video_outlier, e.g. 2.5). If omitted, uses the single metric/threshold params instead. |
| metric | string | null | What to measure: `subs_24h` (subscriber gain in last 24h), `views_24h` (view gain), `subscriber_count`, `avg_views`, `total_videos`, `view_count`, `avg_duration`, `video_outlier` (new video's views vs channel avg), or `new_channels` (count of new search matches — search target only). |
| threshold | number | null | Fire when the metric value is >= this number. E.g. `5000` with metric `subs_24h` means "fire when channel gains 5000+ subs in 24h". For `video_outlier`, this is a float multiplier — e.g. `2.5` fires when a new video gets 2.5x or more views than the channel's average per video. |

### `pause_alert`

Pause an alert without deleting it. Resume later with `unpause_alert`.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| alert_id | integer | required | Alert ID from `list_alerts` |

### `unpause_alert`

Resume a previously paused alert.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| alert_id | integer | required | Alert ID from `list_alerts` |

### `delete_alert`

Permanently delete an alert. Also deletes all its triggered_alerts history.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| alert_id | integer | required | Alert ID from `list_alerts` |

### `get_outlier_alert_status`

Get diagnostic status for the user's `video_outlier` alerts. Returns what the nightly evaluator looked at, what it skipped and why, and the top 10 near-miss channels. Use this to answer "what did my alert find yesterday" or "why hasn't it fired yet". Unlike `get_triggered_alerts`, this shows every run — including ones where nothing met the threshold. Data is from the last evaluator run (a `checked_at_human` field like "3 hours ago" tells you how fresh).

**Example prompt**

"What's the status of my outlier alerts? How close are any of them to firing?"

### `get_triggered_alerts`

Get the user's alert inbox — the morning-briefing tool. By default returns alerts that have fired since the user last checked and marks them as seen. Set `include_acknowledged=true` for read-only history mode.

**Example prompt**

"Any alerts this morning?"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| since | string | null | Optional duration filter: `24h`, `7d`, `30d`. Limits results to alerts that fired within this window. |
| include_acknowledged | boolean | false | Default false (inbox mode). Set `true` for read-only history mode that includes already-seen alerts and does NOT mark new ones as seen. |