Update a watch

PATCH /v1/watches/:id updates selected watch fields. Send only what changes.

string

required

Watch id (watch_...).

Tenant scope

Writes are owner-scoped: another tenant’s watch id is 404 WATCH_NOT_FOUND, never 403. Restricted (sk_*) keys always write to 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 write. Overrides the X-AISearch-On-Behalf-Of header when both are sent.

Body

Every body field is optional.

name

string

New display name.

schedule

object

New cadence as { "every": "15m|30m|1h|6h|12h|1d|7d" } or { "intervalMinutes": integer }. The interval must meet the plan floor.

extract

boolean | object

New Auto Extract config. true and {} enable opportunistic extraction; { "targets": [...] } pins up to 10 targets of at most 100 characters each; false disables extraction.

webhookUrl

string | null

New public HTTPS destination. Send null to remove the webhook.

status

string

active or paused only. Pausing sets pausedReason: "user". Resuming from paused clears pausedReason and reschedules nextRunAt to now + intervalMinutes.

You cannot set status: "canceled" with PATCH. Use DELETE /v1/watches/:id to soft-cancel the watch.

Request

curl -X PATCH https://api.aisearchapi.dev/v1/watches/watch_8f2c1a7e \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": { "every": "6h" },
    "extract": { "targets": ["HubSpot", "attio.com"] },
    "status": "active"
  }'

const res = await fetch(
  'https://api.aisearchapi.dev/v1/watches/watch_8f2c1a7e',
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      schedule: { every: '6h' },
      extract: { targets: ['HubSpot', 'attio.com'] },
      status: 'active',
    }),
  },
);
const { watch } = await res.json();

import os, requests

res = requests.patch(
    "https://api.aisearchapi.dev/v1/watches/watch_8f2c1a7e",
    headers={
        "Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "schedule": {"every": "6h"},
        "extract": {"targets": ["HubSpot", "attio.com"]},
        "status": "active",
    },
)
watch = res.json()["watch"]

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": "6h", "intervalMinutes": 360 },
    "status": "active",
    "pausedReason": null,
    "nextRunAt": "2026-07-11T20:30:00Z",
    "lastRunAt": "2026-07-11T14:00:00Z",
    "lastJobId": "job_8t2q",
    "createdAt": "2026-07-01T14:00:00Z"
  }
}

watch

object

The complete public Watch after the update. The schedule always includes both every and source-of-truth intervalMinutes.

Errors

400

VALIDATION_FAILED

An update field is invalid, including status: "canceled", a malformed schedule, or an invalid extraction target.

404

WATCH_NOT_FOUND

No watch exists for the given id, or it belongs to another tenant.

422

WATCH_INTERVAL_TOO_SHORT

The new schedule is below the plan’s minimum interval. The message names the floor and plan.

422

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

Watches

Lifecycle, plan limits, billing, and run history.

Get a watch

Read the current configuration and recent runs.

Delete a watch

Soft-cancel a watch permanently.

Webhooks

Verify signed deliveries from watch runs.

Endpoints

Account & discovery

Watches

By surface

Tenant scope

Body

Request

Response

Errors

Watches

Get a watch

Delete a watch

Webhooks

​Tenant scope

​Body

​Request

​Response

​Errors

​Related

Watches

Get a watch

Delete a watch

Webhooks

Tenant scope

Body

Request

Response

Errors

Related