---
title: "List your live watches"
method: GET
path: "/v1/watches"
---

# List your live watches

`GET /v1/watches`

## Request

- Base URL: `https://api.reqbeat.com`
- URL: `https://api.reqbeat.com/v1/watches`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

The caller's own live watches -- what is currently subscribed on their
customer, newest first, canceled ones excluded.

A "Watch this search" signup lands with a watch already installed, and
this is where its owner confirms what it watches and which endpoint it
delivers to. Not billable, like the other self-serve introspection
reads (`/webhook-deliveries`): reading your own subscriptions is
account management, not metered corpus access.

Each watch also reports `fires_last_hour` against its declared
`max_fires_per_hour`, and `rate_limited` when the two have met: fires past
that cap are DROPPED rather than queued, so this is the only place a
saturated watch can be told from a quiet one.

And each reports its heartbeat -- `last_fired_at`, `fires_last_7d`,
`fires_last_30d` and a one-word `status` -- so a watch that is silent
because nobody is hiring reads differently from one that is silent because
its criteria can never match, its plan stopped it, or its endpoint is
down. Absence is the customer's only evidence a watch is mis-specified,
and for a metered product it is also the receipt for the months where the
honest answer is "nothing matched".

Requires the `webhooks` scope.

## Response `200`

Successful Response

- WatchResponse[]
  - `id` integer, required
  - `company_id` integer, nullable
  - `criteria` Criteria: A closed AND-of-ORs over three namespaced groups. At least one field must be constrained.
    - `event` CriteriaEvent: The `event` criteria group: AND across fields, OR within a field.
      - `company_id` integer[]
      - `event_type` string[]
      - `board` string[]
      - `source_type` string[]
      - `ats_vendor` string[]
      - `function` string[]
      - `country` string[]
    - `req` CriteriaReq: The `req` criteria group: AND across fields, OR within a field.
      - `seniority_level` string[]
      - `function` string[]
      - `remote_type` string[]
      - `skills` string[]
      - `q` string[]
      - `location` string[]
      - `q_excludes` string[]
    - `company` CriteriaCompany: The `company` criteria group: AND across fields, OR within a field.
      - `industry` string[]
      - `company_kind` string[]
      - `country` string[]
      - `headcount_band` string[]
      - `industry_terms` string[]
    - `max_fires_per_hour` integer
    - `dedup_window_days` integer
  - `event_types` string[], required
  - `webhook_endpoint_id` integer, required
  - `created_at` string, date-time, required
  - `fires_last_hour` integer, required
  - `max_fires_per_hour` integer, required
  - `rate_limited` boolean, required
  - `last_fired_at` string, date-time, nullable
  - `fires_last_7d` integer, required
  - `fires_last_30d` integer, required
  - `status` string, required

## Other responses

- `401`: No API key was sent.
- `403`: The presented key is invalid or revoked, or (see `x-required-scope` on this operation) it does not carry the scope this operation requires.

---

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