Map API

概述

POST /v1/map 用于获取站点内的 URL 列表。

请求

Endpoint

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

Headers

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

请求体

顶层字段

字段	类型	必填	默认值	说明
`url`	string	是	-	站点入口 URL
`filter`	string	否	-	正则表达式：仅返回匹配的 URL
`limit`	integer	否	`5000`	URL 数量上限，最大允许 `100000`
`include_subdomains`	boolean	否	`true`	是否包含子域名
`ignore_query_parameters`	boolean	否	`true`	是否忽略携带 query 参数的 URL

响应

字段	类型	说明
`map_id`	string	任务 ID
`endpoint`	string	固定为 `map`
`version`	string	版本标识
`status`	string	`completed`
`url`	string	入口 URL
`data`	object	URL 列表数据
`started_at`	string	任务开始时间（ISO 8601）
`ended_at`	string	任务结束时间（ISO 8601）
`total_credits_used`	integer	总积分消耗

data 字段说明：

links：URL 列表
total_links：总链接数
credits_used：本次任务消耗的积分
credits_detail：本次任务消耗的积分详情

示例

请求示例

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

响应示例

{
  "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
}