Get a watch

GET /v1/watches/:id returns one watch plus its most recent runs, newest first.

string

required

Watch id (watch_...).

Tenant scope

Reads are owner-scoped: another tenant’s watch id is 404 WATCH_NOT_FOUND, never 403. Restricted (sk_*) keys always read their own owner. Internal keys can act on behalf of one tenant for watch reads and writes with ?owner=<ownerId> or X-AISearch-On-Behalf-Of: <ownerId>; the query parameter wins when both are present. A restricted key’s override is ignored. When an override is applied, the response adds a top-level owner field and an X-AISearch-Owner header containing the enforced owner id.

owner

string

Internal keys only. Owner id to enforce for this read. Overrides the X-AISearch-On-Behalf-Of header when both are sent.

Request

curl https://api.aisearchapi.dev/v1/watches/watch_8f2c1a7e \
  -H "Authorization: Bearer $AISEARCH_API_KEY"

const res = await fetch(
  'https://api.aisearchapi.dev/v1/watches/watch_8f2c1a7e',
  { headers: { Authorization: `Bearer ${process.env.AISEARCH_API_KEY}` } },
);
const { watch, runs } = await res.json();

import os, requests

res = requests.get(
    "https://api.aisearchapi.dev/v1/watches/watch_8f2c1a7e",
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
)
body = res.json()
watch, runs = body["watch"], body["runs"]

Response

200 OK

{
  "watch": {
    "id": "watch_8f2c1a7e",
    "name": "Startup CRM monitor",
    "query": "best crm for startups",
    "surfaces": ["chatgpt", "perplexity"],
    "regions": [{ "country": "US" }],
    "extract": { "targets": ["HubSpot", "attio.com"] },
    "webhookUrl": "https://example.com/hooks/aisearch",
    "schedule": { "every": "1d", "intervalMinutes": 1440 },
    "status": "active",
    "pausedReason": null,
    "nextRunAt": "2026-07-12T14:00:00Z",
    "lastRunAt": "2026-07-11T14:00:00Z",
    "lastJobId": "job_8t2q",
    "createdAt": "2026-07-01T14:00:00Z"
  },
  "runs": [
    {
      "id": "wrun_2b7d4e9a",
      "watchId": "watch_8f2c1a7e",
      "jobId": "job_8t2q",
      "scheduledFor": "2026-07-11T14:00:00Z",
      "status": "dispatched",
      "detail": "search job dispatched",
      "createdAt": "2026-07-11T14:00:01Z"
    }
  ]
}

watch

object

The public Watch object, including its query, surfaces, regions, extraction config, webhook URL, normalized schedule, lifecycle state, and timestamps.

runs

object[]

Up to 10 most recent runs, newest first. Use GET /v1/watches/:id/runs for full history.

Show run

string

Run id (wrun_...).

watchId

string

Owning watch id.

jobId

string | null

Created parent search job, or null when skipped.

scheduledFor

string

Tick this run represents, ISO-8601.

status

string

dispatched, skipped_credits, skipped_limit, or failed.

detail

string

Human-readable outcome detail.

createdAt

string

Run-row creation time, ISO-8601.

For a dispatched run, read its jobId with GET /v1/jobs/:id exactly like any other async search.

Errors

404

WATCH_NOT_FOUND

No watch exists for the given id, or it belongs to another tenant. Reads and writes are owner-scoped, so another tenant’s id is a 404, never a 403.

404

{
  "code": "WATCH_NOT_FOUND",
  "error": "no watch with id 'watch_8f2c1a7e'",
  "request_id": "req_9f2c1a7e4b5d48f1a3c6e8d0b2a4f6c8",
  "docs_url": "https://docs.aisearchapi.dev/guides/errors#watch_not_found"
}

Watches

Scheduling, lifecycle, billing, and run history.

Watch runs

Page through the complete run history.

Update a watch

Pause, resume, or change the configuration.

Read a job

Inspect a dispatched run’s parent job.

Endpoints

Account & discovery

Watches

By surface

Tenant scope

Request

Response

Errors

Watches

Watch runs

Update a watch

Read a job

​Tenant scope

​Request

​Response

​Errors

​Related

Watches

Watch runs

Update a watch

Read a job

Tenant scope

Request

Response

Errors

Related