Map API

Overview

POST /v1/map returns a list of URLs within a site.

Request

Endpoint

POST https://run.xcrawl.com/v1/map

Headers

Content-Type: application/json
Authorization: Bearer <api_key>

Request body

Top-level fields

Field	Type	Required	Default	Description
`url`	string	Yes	-	Site entry URL
`filter`	string	No	-	Regex filter for URLs
`limit`	integer	No	`5000`	Max URLs (up to `100000`)
`include_subdomains`	boolean	No	`true`	Include subdomains
`ignore_query_parameters`	boolean	No	`true`	Ignore URLs with query parameters

Response

Field	Type	Description
`map_id`	string	Task ID
`endpoint`	string	Always `map`
`version`	string	Version
`status`	string	`completed`
`url`	string	Entry URL
`data`	object	URL list data
`started_at`	string	Start time (ISO 8601)
`ended_at`	string	End time (ISO 8601)
`total_credits_used`	integer	Total credits used

data fields:

links: list of URLs
total_links: total count
credits_used: credits used
credits_detail: credit breakdown

Examples

Request example

{
  "url": "https://docs.xcrawl.com/doc/",
  "limit": 5
}

Response example

{
  "map_id": "01KKE88ET3XC7HMPE4CNQNCGSW",
  "endpoint": "map",
  "version": "dca0d4b3bff035e4",
  "status": "completed",
  "url": "https://docs.xcrawl.com/doc/",
  "data": {
    "links": [
      "https://docs.xcrawl.com/",
      "https://docs.xcrawl.com/doc/",
      "https://docs.xcrawl.com/zh/",
      "https://docs.xcrawl.com/doc/introduction/",
      "https://docs.xcrawl.com/zh/doc/"
    ],
    "total_links": 5,
    "credits_used": 1,
    "credits_detail": {
      "base_cost": 1,
      "traffic_cost": 0,
      "json_extract_cost": 0
    }
  },
  "started_at": "2026-03-11T10:49:39Z",
  "ended_at": "2026-03-11T10:49:40Z",
  "total_credits_used": 1
}