Delete a watch

DELETE /v1/watches/:id sets a watch to canceled. It does not hard-delete the row or its run history.

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.

Request

This endpoint has no request body.

curl -X DELETE 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',
  {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${process.env.AISEARCH_API_KEY}` },
  },
);
const { watch } = await res.json();

import os, requests

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

Response

200 OK

{
  "watch": {
    "id": "watch_8f2c1a7e",
    "status": "canceled"
  }
}

watch.id

string

The watch id.

watch.status

string

Always canceled after the soft delete.

A canceled watch stops scheduling new runs. Existing run history stays readable with GET /v1/watches/:id/runs.

Errors

404

WATCH_NOT_FOUND

No watch exists for that id, or it belongs to another tenant (reads and writes are owner-scoped — 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

Lifecycle, scheduling, billing, and auto-pause behavior.

Watch runs

Read preserved run history after cancellation.

Get a watch

Read the watch and its recent runs.

Create a watch

Create a new scheduled query.

Endpoints

Account & discovery

Watches

By surface

Tenant scope

Request

Response

Errors

Watches

Watch runs

Get a watch

Create a watch

​Tenant scope

​Request

​Response

​Errors

​Related

Watches

Watch runs

Get a watch

Create a watch

Tenant scope

Request

Response

Errors

Related