---
title: "Submit a sitemap crawl and get a quote"
method: POST
path: "/sitemap"
tags: ["Sitemap"]
---

# Submit a sitemap crawl and get a quote

`POST /sitemap`

## Request

- Base URL: `https://request.usestring.ai/v1`
- URL: `https://request.usestring.ai/v1/sitemap`
- Auth: HTTP bearer

Submit an asynchronous crawl that discovers the URLs on one hostname from a starting URL, and get a cost quote. Nothing is crawled or charged until you call approveSitemapJob, within one hour. Use it to map a site's pages; use fetchUrl to read a page. Also served under `/map` with the same shapes.

## Request body

- SitemapCreateRequest: Request body for POST /sitemap. Any other field is rejected with a 400.
  - `url` string, uri, required: Starting URL. The crawl stays on this hostname.
  - `maxPages` integer: Maximum pages to crawl.
  - `maxDepth` integer: Maximum link depth from the starting URL.
  - `pathPrefix` string: Only crawl URLs whose path starts with this prefix.
  - `budgetUsd` number: Spend cap in USD. Defaults to the quote itself, so every job is capped; the crawl stops with `token_cap_exceeded` before exceeding it.
  - `useSitemap` boolean: Also seed the crawl from the site's root /sitemap.xml (one extra quoted and billed page).

## Response `202`

Quote produced; job awaiting approval.

- SitemapQuote: A new job in `awaiting_approval`. Nothing is crawled or charged until approved. Quotes expire after one hour.
  - `jobId` string, required
  - `status` 'awaiting_approval', required
  - `estimatedCostUsd` string, required: Quoted cost in USD, as a decimal string.
  - `estimatedPages` integer, required

## Other responses

- `400`: Validation error: invalid input or an unrecognized field. `issues` lists per-field problems.
- `401`: Missing or invalid Authorization header.
- `403`: Destination domain not enabled for your organization. Email support@usestring.ai to request access.
- `429`: Rate limit exceeded. The default limit is 60 requests per second per organization, averaged over a rolling window. Back off and retry with exponential backoff and jitter.
- `500`: Internal server error.

---

[API](https://skmtc.dev/usestring/apis/string-web-access-api.md) · [All operations](https://skmtc.dev/usestring/apis/string-web-access-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usestring/apis/string-web-access-api/revisions/fd336960036e?raw)