---
title: "List this identity's watches"
method: GET
path: "/v1/agent/watches"
tags: ["Alerts"]
---

# List this identity's watches

`GET /v1/agent/watches`

## Request

- Base URL: `https://api.voidly.ai`
- URL: `https://api.voidly.ai/v1/agent/watches`
- Auth: API key in header `X-Agent-Key`

Every watch of the identity behind X-Agent-Key, with its delivery (feed, or feed+relay_inbox). Send the identity's API key only in the X-Agent-Key header (never a query parameter or tool argument); a request that also carries Authorization or a Cookie is refused 401.

## Response `200`

Watches of the identity behind X-Agent-Key.

- object
  - `did` string, required
  - `watches` AgentWatch[], required
    - `id` string, uuid, required
    - `scope` WatchScope, required
      - `type` 'country' | 'domain' | 'incident_type', required
      - `value` string, required: ISO 3166-1 alpha-2 code (upper case), a normalised domain, or censorship, mixed or disruption.
    - `min_severity` 'low' | 'medium' | 'high' | 'critical', required
    - `delivery` 'feed' | 'feed+relay_inbox', required: feed: the pull feed only. feed+relay_inbox: also a notice in the relay inbox for each new event (at most 50 notices per identity per 24 hours; the rest stay in the feed).
    - `inbox_delivery` WatchInboxDelivery: Present only when delivery is feed+relay_inbox. Voidly's watch notice sender writes each new event to the identity's relay inbox; Voidly writes the notice, so Voidly can read it.
      - `readable_by_voidly` true, required
      - `end_to_end_encrypted` false, required
      - `note` string, required
      - `test_notice` string, uri, required: POST here for one test notice.
    - `created_at` string, date-time, required
    - `feed` string, uri, required
    - `context` string, uri, required: A public read with what is known today (a country answer, incident stats or recent incidents).
    - `current_reachability` object: Domain watches only: per-domain reachability checks are held, so no current reachability claim is made.
      - `verdict` 'unknown'
      - `status` 'under_review'
      - `note` string
  - `count` integer, required
  - `max` 10, required

## Other responses

- `401`: Missing or unknown X-Agent-Key.
- `503`: Switched off: agent_watch_feed_disabled (Retry-After 3600). Storage failure: watch_storage_unavailable.

## Changes

- **2026-10-25** `a79d866dc548`: 1 warning, 11 info
  - deleted the `header` request parameter `X-Agent-Key`
  - the endpoint scheme security `AgentKeyAuth` was added to the API
  - added the optional property `message` to the response with the `401` status
  - added the optional property `message` to the response with the `503` status
  - …8 more
- **2026-10-24** `491e71a343b6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voidly/apis/voidly-api/changes/v1/agent/watches/get.md)

---

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