---
title: "Discover URLs on a site"
method: POST
path: "/v2/map"
---

# Discover URLs on a site

`POST /v2/map`

## Request

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

## Headers

- `Idempotency-Key` string

## Request body

- UrlJobRequest
  - `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
  - `limit` integer: Effective adapter maximum: 500. Higher values fail with provider_limit_exceeded.
  - `include` string[]
  - `exclude` string[]
  - `maxDepth` integer: Forwarded to the map/crawl adapter.
  - `includeSubdomains` boolean
  - `respectRobots` boolean
  - `useSitemap` boolean

## 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)