---
title: "Search the web"
method: POST
path: "/v2/search"
---

# Search the web

`POST /v2/search`

## Request

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

30 DeepSFetch credits per successful search request, including zero matches, up to 20 results. Failed provider calls are not charged. Scraping is a separate operation. Use Idempotency-Key to replay without an additional charge.

## Headers

- `Idempotency-Key` string

## Request body

- SearchRequest
  - `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.
  - `query` string, required
  - `limit` integer
  - `scrapeResults` false: Use /v2/scrape separately. Combined search and scraping is not supported.
  - `source` 'web' | 'news' | 'images': Web pages, news articles or images. One provider request per search.
  - `category` 'general' | 'developer' | 'research': Domain allowlist for Web results; use general with News or Images. No additional DeepSFetch credits.
  - `sources` string[]: Combine Web, News, Images, Developer and Research. Developer and Research use domain filters without additional DeepSFetch credits.

## Response `200`

Completed

- 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

- `202`: Accepted
- `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)