---
title: "Create Crawl Graph"
method: POST
path: "/crawl/graph"
tags: ["crawling"]
---

# Create Crawl Graph

`POST /crawl/graph`

Create a crawl graph by recursively crawling from a root URL

This endpoint crawls a website starting from the given URL up to the specified depth,
extracting links and building a graph structure. Results are checkpointed.

Requires permission: crawl:write

## Request body

- CrawlGraphRequest — Request model for crawl graph generation
  - `url` string, uri, required — Root URL to start crawling from
  - `engines` EngineType[], required — List of engines to use
  - `crawl_id` string, required — Unique identifier for this crawl
  - `depth` integer, nullable — Maximum crawl depth
  - `absolute_only` boolean — Only extract absolute URLs
  - `keep_external` boolean — Keep external URLs in results
  - `visit_external` boolean — Visit external URLs
  - `max_workers` integer — Maximum concurrent workers
  - `batch_size` integer — URLs per batch
  - `max_urls` integer — Maximum URLs to crawl
  - `debug` boolean — Enable debug information

## Response `200`

Successful Response

- CrawlGraphResponse — Response model for crawl graph generation
  - `crawl_id` string, required
  - `root_url` string, required
  - `total_pages_visited` integer, required
  - `visited_urls` string[], required
  - `depth_reached` integer, required
  - `max_depth` integer, required
  - `max_urls` integer, required
  - `absolute_only` boolean, required
  - `keep_external` boolean, required
  - `visit_external` boolean, required
  - `max_workers` integer, required
  - `batch_size` integer, required
  - `timestamp` string, required
  - `debug_frame` object[], nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-02-17** `29225d7b3ea4` — 1 warning, 2 info
  - removed the request property `s3_bucket`
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2025-09-18** `019c4555bd7f` — 1 info
  - added the new `ASYNC_FLEET_STICKY` enum value to the request property `engines/items/`
- **2025-08-12** `707c0eb9cee1` — 2 breaking, 5 info
  - request property `engines/items/` was restricted to a list of enum values
  - the `engines/items/` request property type/format changed from `object`/`` to `string`/``
  - added the new `FLEET` enum value to the request property `engines/items/`
  - added the new `FLEET_ASYNC` enum value to the request property `engines/items/`
  - …3 more

[Change history](https://skmtc.dev/evrimai/apis/cartography-server/changes/crawl/graph/post.md)

---

[API](https://skmtc.dev/evrimai/apis/cartography-server.md) · [All operations](https://skmtc.dev/evrimai/apis/cartography-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/evrimai/cartography-server/revisions/5ee44bc43d24/schema)