Create a watch

POST /v1/watches creates an active watch that re-runs a saved query on a cadence.

POST https://api.aisearchapi.dev/v1/watches

Every request needs Authorization: Bearer <API_KEY> and Content-Type: application/json.

Creating a watch is free. Credits are reserved only when a scheduled run dispatches, using the same per-surface, success-only billing as an async search. A skipped run costs nothing.

Watches can also be created from the dashboard Watches page or by an agent through the create_watch tool on the MCP server — every path hits this same endpoint with identical validation, plan limits, and billing.

Tenant scope

Restricted (sk_*) keys always create watches for their own owner. Internal keys can act on behalf of one tenant for 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.

owner

string

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

Body

name

string

default:""

Optional display name. Omitted watches use an empty string.

query

string

required

The exact prompt to run on every tick. Non-empty, up to 2000 characters. This endpoint does not accept the prompt alias.

surfaces

string[]

required

One or more surfaces. Allowed values: chatgpt, claude, perplexity, gemini, copilot, google_ai_overview, google_ai_mode, google_search, google_news.

regions

object[]

Up to 10 regions. Omitted: one untargeted (GLOBAL) run per surface.

Show region object

country

string

required

ISO-3166 alpha-2 country code, e.g. US.

state

string

Optional state or first-level administrative area.

city

string

Optional city.

language

string

Optional BCP-47 language hint.

extract

boolean | object

Auto Extract configuration re-applied on every dispatched run. true and {} extract opportunistically; false or omission disables extraction.

Show extract object

targets

string[]

Up to 10 pinned brand names or bare domains, each non-empty and at most 100 characters. Pinned targets are reported whether present or absent.

webhookUrl

string

Public HTTPS endpoint that receives each dispatched run’s signed deliveries. Private, loopback, link-local, and metadata destinations are rejected.

schedule

object

required

Cadence in one of two forms. The interval must meet your plan’s floor.

Show schedule object

every

string

One of 15m, 30m, 1h, 6h, 12h, 1d, or 7d.

intervalMinutes

integer

Positive integer for an off-grid cadence. Send either this field or every, not both.

Request

curl -X POST https://api.aisearchapi.dev/v1/watches \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best crm for startups",
    "surfaces": ["chatgpt", "perplexity"],
    "regions": [{ "country": "US" }],
    "schedule": { "every": "1d" }
  }'

const res = await fetch('https://api.aisearchapi.dev/v1/watches', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'best crm for startups',
    surfaces: ['chatgpt', 'perplexity'],
    regions: [{ country: 'US' }],
    schedule: { every: '1d' },
  }),
});

const { watch } = await res.json();

import os, requests

res = requests.post(
    "https://api.aisearchapi.dev/v1/watches",
    headers={
        "Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "query": "best crm for startups",
        "surfaces": ["chatgpt", "perplexity"],
        "regions": [{"country": "US"}],
        "schedule": {"every": "1d"},
    },
)

watch = res.json()["watch"]

Response

201 Created

{
  "watch": {
    "id": "watch_8f2c1a7e",
    "name": "",
    "query": "best crm for startups",
    "surfaces": ["chatgpt", "perplexity"],
    "regions": [{ "country": "US" }],
    "extract": null,
    "webhookUrl": null,
    "schedule": { "every": "1d", "intervalMinutes": 1440 },
    "status": "active",
    "pausedReason": null,
    "nextRunAt": "2026-07-12T14:00:00Z",
    "lastRunAt": null,
    "lastJobId": null,
    "createdAt": "2026-07-11T14:00:00Z"
  }
}

watch

object

The created public Watch.

Show watch

string

Watch id (watch_...).

name

string

Display name; "" when omitted.

query

string

Saved query.

surfaces

string[]

Surfaces run on each tick.

regions

object[]

Saved region objects.

extract

object | null

Normalized extraction config, or null when disabled.

webhookUrl

string | null

Delivery destination, or null.

schedule

object

Both every and the source-of-truth intervalMinutes.

status

string

active, paused, or canceled.

pausedReason

string | null

Pause reason when present, e.g. user or insufficient_credits.

nextRunAt

string

Next scheduled tick, ISO-8601.

lastRunAt

string | null

Most recent tick, or null.

lastJobId

string | null

Parent job id from the most recent run, when present.

createdAt

string

Creation time, ISO-8601.

Responses always echo both schedule fields. For an off-grid interval, every is a display convenience; intervalMinutes is the source of truth.

Errors

Code	Status	When
`VALIDATION_FAILED`	400	A body field, schedule form, region, or extraction target is invalid.
`AUTH_INVALID`	401	The API key is missing, invalid, or revoked.
`WATCH_LIMIT_EXCEEDED`	403	Creating the watch would exceed the plan’s active-watch ceiling.
`WATCH_INTERVAL_TOO_SHORT`	422	The requested interval is below the plan’s minimum.

Creating a watch never returns INSUFFICIENT_CREDITS: creation costs 0 credits, and credits are considered only when a run dispatches.

422

{
  "code": "WATCH_INTERVAL_TOO_SHORT",
  "error": "minimum watch interval is 1440 minutes on the free plan",
  "request_id": "req_9f2c1a7e4b5d48f1a3c6e8d0b2a4f6c8",
  "docs_url": "https://docs.aisearchapi.dev/guides/errors#watch_interval_too_short"
}

Watches

Scheduling, limits, lifecycle, billing, and run history.

List watches

Page through the owner’s watches.

Update a watch

Change the cadence, extraction, webhook, or status.

Webhooks

Verify signed deliveries from dispatched runs.

Endpoints

Account & discovery

Watches

By surface

Tenant scope

Body

Request

Response

Errors

Watches

List watches

Update a watch

Webhooks

​Tenant scope

​Body

​Request

​Response

​Errors

​Related

Watches

List watches

Update a watch

Webhooks

Tenant scope

Body

Request

Response

Errors

Related