---
title: "List watches"
method: POST
path: "/list_watches"
---

# List watches

`POST /list_watches`

## Request

- Base URL: `https://newsmind.app/api/v1`
- URL: `https://newsmind.app/api/v1/list_watches`
- Auth: OAuth 2 (authorization code, authorization URL `https://newsmind.app/oauth/authorize`, token URL `https://newsmind.app/oauth/token`, scopes: `mcp`)

Return the user's saved watches with scope, delivery, active state, and current unseen-match counts. Read-only.

## Request body

- object

## Response `200`

Success

- object
  - `count` integer
  - `watches` WatchWithCount[]
    - `watch_id` integer, required
    - `query` string, required
    - `label` string, nullable
    - `feed_id` integer, nullable
    - `folder` string, nullable
    - `kind` 'keyword' | 'semantic', required
    - `threshold` number, nullable
    - `active` boolean, required
    - `delivery` 'in_session' | 'email' | 'webhook', required
    - `cadence` 'realtime' | 'weekdays' | 'daily' | 'weekly', nullable
    - `require_terms` string[], nullable
    - `exclude_terms` string[], nullable
    - `delivery_hour` integer, nullable
    - `delivery_day` string, nullable
    - `webhook_url` string, nullable
    - `created_at` string, date-time, required
    - `new_match_count` integer, nullable, required: Unseen matches, counted as stories exactly as get_watch_matches groups them. Null when the count could not be read on this call (the response's unavailable says so) — unknown, never a guessed 0.
  - `unavailable` object: Present only when a watch's unseen-match count could not be read on this call. Names the field and says where the matches are; those watches carry new_match_count null.
    - `new_match_count` string

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `402`: Subscription required (trial expired or cancelled)
- `429`: Too many calls. Either the per-account rate limit ({error: "rate_limited", message}) or the account's in-flight work ({error: <sentence>, code: "busy"}). Wait Retry-After seconds.
- `500`: Server error on our side (error: internal_error). The team has been notified.
- `503`: Temporarily unable to answer. error: timeout (the request ran too long; narrow it), server_busy or tier_unavailable (retry after Retry-After seconds when sent).

---

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