List watches

GET /v1/watches returns the owner’s watches, newest first, with cursor pagination.

Tenant scope

Restricted (sk_*) keys see only their own watches. Internal keys can act on behalf of one tenant for watch reads and writes by sending ?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.

status

string

Filter by active, paused, or canceled.

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

const res = await fetch(
  'https://api.aisearchapi.dev/v1/watches?limit=20&status=active',
  { 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",
    params={"limit": 20, "status": "active"},
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
)
page = res.json()

Response

200 OK

{
  "items": [
    {
      "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"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjIwfQ"
}

items

object[]

Public Watch objects, newest first.

Show item

string

Watch id (watch_...).

name

string

Display name.

query

string

Saved query.

surfaces

string[]

Surfaces run on each tick.

regions

object[]

Saved region objects.

extract

object | null

Saved extraction config, or null.

webhookUrl

string | null

Delivery destination, or null.

schedule

object

every plus source-of-truth intervalMinutes.

status

string

active, paused, or canceled.

pausedReason

string | null

Why the watch is paused, when present.

nextRunAt

string

Next scheduled tick, ISO-8601.

lastRunAt

string | null

Most recent tick, or null.

lastJobId

string | null

Most recent parent job id, when present.

createdAt

string

Creation time, ISO-8601.

nextCursor

string | null

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

Paginate to the end

cursor=""
while true; do
  url="https://api.aisearchapi.dev/v1/watches?limit=100"
  [ -n "$cursor" ] && url="$url&cursor=$cursor"
  page=$(curl -s "$url" -H "Authorization: Bearer $AISEARCH_API_KEY")
  printf '%s\n' "$page" | jq -r '.items[] | [.id, .status] | @tsv'
  cursor=$(printf '%s\n' "$page" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done

async function* allWatches() {
  let cursor;
  do {
    const url = new URL('https://api.aisearchapi.dev/v1/watches');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.AISEARCH_API_KEY}` },
    });
    const page = await res.json();
    yield* page.items;
    cursor = page.nextCursor;
  } while (cursor);
}

for await (const watch of allWatches()) console.log(watch.id, watch.status);

import os, requests

def all_watches():
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(
            "https://api.aisearchapi.dev/v1/watches",
            params=params,
            headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
        )
        page = res.json()
        yield from page["items"]
        cursor = page["nextCursor"]
        if not cursor:
            break

for watch in all_watches():
    print(watch["id"], watch["status"])

Errors

401

AUTH_INVALID

The API key is missing, invalid, or revoked.

401

{
  "code": "AUTH_INVALID",
  "error": "missing or invalid API key; send Authorization: Bearer <API_KEY>",
  "request_id": "req_9f2c1a7e4b5d48f1a3c6e8d0b2a4f6c8",
  "docs_url": "https://docs.aisearchapi.dev/guides/errors#auth_invalid"
}

Watches

Scheduling, lifecycle, billing, and run history.

Create a watch

Save a new scheduled query.

Get a watch

Read one watch and its ten most recent runs.

Watch runs

Page through full run history.

Endpoints

Account & discovery

Watches

By surface

Tenant scope

Query parameters

Request

Response

Paginate to the end

Errors

Watches

Create a watch

Get a watch

Watch runs

​Tenant scope

​Query parameters

​Request

​Response

​Paginate to the end

​Errors

​Related

Watches

Create a watch

Get a watch

Watch runs

Tenant scope

Query parameters

Request

Response

Paginate to the end

Errors

Related