---
title: "List your board watches"
method: GET
path: "/api/v1/watches"
tags: ["Board Watches"]
---

# List your board watches

`GET /api/v1/watches`

## Request

- Base URL: `https://api.vaquill.ai`
- URL: `https://api.vaquill.ai/api/v1/watches`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/vaquill/apis/vaquill-developer-api/docs/api/v1/watches/get.ts> (a function with typed inputs; its response is checked against the schema)

List every board watch you own, across every channel and board. Use this to check a watch's `id` for the update/delete/test/deliveries routes below, or to see `lastNotifiedAt`/`lastStatus` for a quick health check without opening the deliveries endpoint.

Free.

## Query parameters

- `limit` integer: Max watches to return.
- `offset` integer: Number of watches to skip, for paging.

## Response `200`

Your board watches.

- WatchesEnvelope
  - `data` WatchesPage, required
    - `watches` WatchResponse[], required
      - `id` string, required
      - `corpusType` string, required
      - `state` string, nullable
      - `channel` string, required
      - `webhookUrl` string, nullable
      - `emailAddress` string, nullable
      - `scope` object, nullable
      - `isActive` boolean, required
      - `createdAt` string, required
      - `updatedAt` string, nullable
      - `lastNotifiedAt` string, nullable
      - `lastStatus` integer, nullable
      - `webhookAuth` WebhookAuthResponse: Auth CONFIG as read back. Never includes the credential itself.
        - `scheme` string, required
        - `headerName` string, nullable
        - `hasSecret` boolean
      - `cadence` string, nullable: How often we poll this board's source: `daily`, `weekly`, `monthly` or `annual`. Same value as `GET /boards`. Watching does not change it, and checking `/changes` more often than this gains nothing.
      - `lastRetrievedAt` string, nullable: ISO-8601 UTC timestamp of the last refresh run for this board that finished cleanly. A run that found nothing new counts.
      - `changeSignal` string: `continuous` or `edition_only`. On an `edition_only` board we can only detect a new edition arriving, so silence on this watch means no new edition, not that the law is unchanged. Full definition on `GET /boards`.
  - `meta` ResponseMeta, required: The `meta` block every board-watch route returns beside `data`.
    - `processingTimeMs` number, required
    - `creditsConsumed` number, required
    - `cursor` integer, nullable: Change feeds only: the value to send back as `sinceId`. Null on an empty page. The highest change `id` on the page, except on a full newest-first page read with a `sinceId`, where unread rows sit below the page and the cursor stays at your `sinceId`; use `nextBeforeId` to reach them.
    - `nextBeforeId` integer, nullable: Change feeds only, full `order=desc` pages: the lowest change `id` on the page. Send it as `beforeId` for the next older page. Null otherwise.
    - `hasMore` boolean, nullable: Change feeds only: true when the page filled to `limit`.

## Other responses

- `401`: Invalid or missing API key.
- `403`: API key lacks `research:read` scope.
- `422`: Validation error: `detail` plus one `errors` entry per rejected field.
- `429`: Rate limit exceeded.
- `500`: Internal error (`internal_error`, retryable). Any credits charged for the call are refunded; retry with backoff and quote `requestId` to support if it persists.

## Changes

- **2026-11-07** `340c0d24d0b6`: 38 info
  - added the non-success response with the status `500`
  - added the optional property `candidateCount` to the response with the `401` status
  - added the optional property `candidateCount` to the response with the `403` status
  - added the optional property `candidateCount` to the response with the `422` status
  - …34 more

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

---

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