---
title: "Discover URLs from sitemaps and page links"
method: POST
path: "/map"
tags: ["Discovery"]
---

# Discover URLs from sitemaps and page links

`POST /map`

## Request

- Base URL: `https://api.domscout.io`
- URL: `https://api.domscout.io/map`
- Auth: API key in header `x-api-key`

Returns a bounded, robots-aware URL map. Sitemap locations and same-site links are deduplicated and canonicalized. The endpoint does not execute JavaScript. Intelligence work has one 18-second synchronous deadline across the complete request.

## Request body

- MapRequest
  - `url` string, uri, required
  - `maxPages` integer
  - `maxDepth` integer
  - `maxUrls` integer
  - `includeSitemap` boolean
  - `discoverLinks` boolean
  - `includePaths` string[]
  - `excludePaths` string[]
  - `allowExternalLinks` boolean

## Response `200`

Discovered URLs.

- MapResponse
  - `status` 'success'
  - `seedUrl` string, uri
  - `urls` object[]
    - `url` string, uri
    - `source` string
    - `depth` integer, nullable
  - `counts` object
    - `urls` integer
    - `pagesFetched` integer
    - `sitemapsFetched` integer
  - `truncated` boolean
  - `limits` object
    - `maxPages` integer
    - `maxDepth` integer
    - `maxUrls` integer
  - `billing` BillingInfo
    - `credits` integer
    - `chargedTo` string, nullable
    - `remaining` integer, nullable
    - `quotaRemaining` integer, nullable
  - `metadata` object: Present only when the request needs something reported back. Currently carries ignoredFields.
    - `ignoredFields` string[]: Top-level request fields this route does not understand. They were ignored, not rejected — existing requests stay valid — but an ignored field changes the answer without changing the price, so it is named here. A misspelling such as maxChunk for maxChunks appears in this array. At most 20 are listed.

## Other responses

- `400`: The request failed validation.
- `403`: The request was refused. Returned when the x-api-key header is missing, revoked, or invalid, and when a valid key is blocked by a plan entitlement, the trusted-JavaScript account entitlement, a global product pause, or a security policy. A plan-only restriction returns code PLAN_FEATURE_UNAVAILABLE and can include upgrade_url. FEATURE_NOT_ENABLED identifies either the global product emergency pause or an eligible Business account without trusted-JavaScript permission; it carries no upgrade_url, so upgrading or retrying cannot clear it. Browser capture can return BROWSER_ISOLATION_REQUIRED or BROWSER_EXECUTION_DENIED with reason public_capture_not_enabled when browser work is unavailable for your account. These platform restrictions carry no upgrade_url and are not resolved by changing plan or key. Check GET /credits for current account capabilities. The API does not use 401: it authenticates with an API key header rather than an HTTP authentication scheme, so there is no WWW-Authenticate challenge to issue.
- `429`: The plan quota or rate limit has been reached.
- `503`: The request work may have completed, but the service could not confirm its usage-finalization write. The response code is `INTELLIGENCE_FINALIZATION_UNCERTAIN`; no result is returned. Its state can be ambiguous (including a possible completed index write), so do not automatically retry. Retain `requestId` and contact support so the outcome can be investigated; any pending usage record is reconciled separately.
- `504`: The shared 18-second synchronous intelligence-work deadline expired. In that case the response code is `INTELLIGENCE_DEADLINE_EXCEEDED`. For a URL-based /extract request, retry with a bounded content or HTML excerpt from the page rather than asking the service to fetch it again; that advice is what the response carries, and when fetching the page alone exhausted the budget the message says so, because no model call was attempted. Other intelligence routes should retry with a smaller input or fewer pages. A provider that reaches its own shorter timeout first retains its provider-specific timeout code.

---

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