List watch runs

GET /v1/watches/:id/runs returns the watch’s run history, newest first, with cursor pagination.

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.

Query parameters

limit

integer

default:"20"

Page size, 1–100.

cursor

string

Opaque cursor from a previous page’s nextCursor. Omit for the first page.

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/runs?limit=20" \
  -H "Authorization: Bearer $AISEARCH_API_KEY"

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

import os, requests

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

Response

200 OK

{
  "items": [
    {
      "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"
    },
    {
      "id": "wrun_6c3a1f8d",
      "watchId": "watch_8f2c1a7e",
      "jobId": null,
      "scheduledFor": "2026-07-10T14:00:00Z",
      "status": "skipped_credits",
      "detail": "insufficient credits at dispatch time",
      "createdAt": "2026-07-10T14:00:01Z"
    }
  ],
  "nextCursor": null
}

items

object[]

Scheduled attempts, newest first.

Show item

string

Run id (wrun_...).

watchId

string

Owning watch id.

jobId

string | null

Created parent job, or null when skipped.

scheduledFor

string

Tick this run represents, ISO-8601.

status

string

Run outcome.

detail

string

Human-readable elaboration.

createdAt

string

Run-row creation time, ISO-8601.

nextCursor

string | null

Pass as ?cursor= to fetch the next page. null on the last page.

Run statuses

Status	Meaning
`dispatched`	A search job was created and `jobId` is set. Read it like any other async job.
`skipped_credits`	Balance was insufficient at dispatch time; nothing was billed. Three consecutive skips pause the watch.
`skipped_limit`	An account or plan ceiling prevented dispatch; nothing was billed.
`failed`	The scheduled attempt failed to submit. A captured-but-empty or failed job is still `dispatched` with a `jobId`.

Errors

404

WATCH_NOT_FOUND

No watch exists for the given id, or it belongs to another tenant. The API does not expose another tenant’s watch or run history.

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 outcomes.

Get a watch

Read a watch with its ten newest runs.

Read a job

Inspect a dispatched run’s parent job.

Webhooks

Receive signed deliveries from dispatched runs.

Endpoints

Account & discovery

Watches

By surface

Tenant scope

Query parameters

Request

Response

Run statuses

Errors

Watches

Get a watch

Read a job

Webhooks

​Tenant scope

​Query parameters

​Request

​Response

​Run statuses

​Errors

​Related

Watches

Get a watch

Read a job

Webhooks

Tenant scope

Query parameters

Request

Response

Run statuses

Errors

Related