---
title: "Create a monitored URL"
method: POST
path: "/v2/watch"
---

# Create a monitored URL

`POST /v2/watch`

## Request

- Base URL: `https://api.deepsfetch.com`
- URL: `https://api.deepsfetch.com/v2/watch`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- WatchRequest
  - `async` boolean
  - `webhook` Webhook: See https://deepsfetch.com/docs/webhooks for HMAC verification and delivery limitations. No automatic webhook retry in the current delivery chain.
    - `url` string, uri, required
    - `secret` string, required
    - `metadata` object: Accepted configuration metadata is not included in the current delivered event payload.
  - `geo` object: Legacy common option. Not forwarded by the HTML adapter or recognized by the current browser runtime. Do not rely on it to customize execution.
    - `country` string
    - `region` string
    - `city` string
    - `language` string
  - `session` object: Legacy common option. Not forwarded by the HTML adapter or recognized by the current browser runtime. Do not rely on it to customize execution.
    - `id` string, required
    - `ttlSeconds` integer
  - `device` 'desktop' | 'mobile' | 'tablet': Legacy common option. Not forwarded by the HTML adapter or recognized by the current browser runtime. Do not rely on it to customize execution.
  - `render` union: For scrape, true or an object selects browser runtime. Nested wait/timeout settings are not runtime settings: use top-level timeoutMs and waitUntil. Browser runtime does not support credit caps.
    - boolean
    - object
      - `waitMs` integer
      - `waitFor` string
      - `timeoutMs` integer
  - `costControl` object: Supported on compatible scrape/map/crawl/extract, independent collection engine and current search paths. Legacy browser runtime/interact and V2 watch creation reject credit caps. External AI costs excluded.
    - `maxCredits` integer: Additional task credit cap. External AI provider costs are excluded.
    - `cacheMode` 'fresh' | 'prefer'
    - `maxAgeSeconds` integer
    - `allowFallback` boolean: Set false to restrict fallback. General estimation includes fallback unless false; quickstart forces false.
    - `taskId` string: Shared task budget identifier within the workspace. Use a new ID per logical run; distinct from idempotency.
  - `url` string, uri, required
  - `schedule` string, required: Minute interval only, e.g. 15m, 1min or 60m; 1–525600 minutes. Cron expressions are unsupported.
  - `changeThreshold` number: Accepted legacy field, ignored by the current adapter. Text and HTML use a fixed change policy.

## Response `202`

Accepted

- Job
  - `id` string, required
  - `kind` 'scrape' | 'extract' | 'search' | 'map' | 'crawl' | 'interact' | 'watch', required
  - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required
  - `result` object, nullable: Provider-specific output. V1 adapter: provider, operation, providerJobId, status, statusUrl, result, meta. Inspect inner status for partial completion; browser shape differs.
  - `error` object, nullable
    - `code` string
    - `message` string
  - `createdAt` string, date-time, required
  - `startedAt` string, nullable
  - `completedAt` string, nullable
  - `cancelledAt` string, nullable

## Other responses

- `400`: Invalid request
- `401`: Unauthorized
- `409`: Idempotency conflict, credit cap exceeded or cost_operation_unsupported. Inspect the error code.
- `429`: Rate limited
- `503`: Provider unavailable

---

[API](https://skmtc.dev/deepsfetch/apis/deepsfetch-api.md) · [All operations](https://skmtc.dev/deepsfetch/apis/deepsfetch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/deepsfetch/apis/deepsfetch-api/revisions/d027e0aecb6f?raw)