---
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 to S3.

Requires permission: crawl:write

## Request body

- CrawlGraphRequest — Request model for crawl graph generation
  - `url` string, uri, required — Root URL to start crawling from
  - `engines` object[], required — List of engines to use
  - `crawl_id` string, required — Unique identifier for this crawl
  - `s3_bucket` string, required — S3 bucket for checkpointing
  - `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

---

[API](https://skmtc.dev/evrimai/apis/cartography-server.md) · [All operations](https://skmtc.dev/evrimai/apis/cartography-server/llms.txt) · [OpenAPI document](https://skmtc.dev/evrimai/apis/cartography-server/revisions/4eb68ae85080?raw)