Search API

概述

POST /v1/search 用于根据关键词、地区、语言等参数获取搜索结果。

请求

Endpoint

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

Headers

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

请求体

顶层字段

字段	类型	必填	默认值	说明
`query`	string	是	-	搜索关键词
`location`	string	否	`US`	地区（国家/城市/地区名称或 ISO 代码；会尽量匹配）
`language`	string	否	`en`	搜索语言（ISO 639-1）
`limit`	integer	否	`10`	返回结果数量上限（1-100）

响应

字段	类型	说明
`search_id`	string	任务 ID
`endpoint`	string	固定为 `search`
`version`	string	版本标识
`status`	string	`completed`
`query`	string	搜索关键词
`data`	object	搜索结果数据
`started_at`	string	任务开始时间（ISO 8601）
`ended_at`	string	任务结束时间（ISO 8601）
`total_credits_used`	integer	总积分消耗

data 字段说明：

data.data：搜索结果数组，每项包含 description、position、title、url
status：搜索提供方返回的状态，例如 success
startedAt / endedAt：搜索提供方返回的开始/结束时间
credits_used：本次搜索消耗的积分
credits_detail：本次搜索消耗的积分详情

示例

请求示例

{
  "query": "site:docs.xcrawl.com XCrawl API",
  "location": "US",
  "language": "en",
  "limit": 2
}

响应示例

{
  "search_id": "01KKE8BNMEKRHJB9GEWXPYQ8E1",
  "endpoint": "search",
  "version": "dca0d4b3bff035e4",
  "status": "completed",
  "query": "site:docs.xcrawl.com XCrawl API",
  "data": {
    "credits_detail": {
      "base_cost": 2,
      "traffic_cost": 0,
      "json_extract_cost": 0
    },
    "credits_used": 2,
    "data": [
      {
        "description": "Webhook Callbacks · Learn more XCrawl. API Reference · Scrape API · Search API · Map API · Crawl API · Learn more XCrawl. Frequently Asked Questions.Read more",
        "position": 1,
        "title": null,
        "url": "https://docs.xcrawl.com/"
      },
      {
        "description": "XCrawl uses Bearer Token authentication. To use the XCrawl API, you need an API key. After signing up, get it from the dashboard. Add request headers.Read more",
        "position": 2,
        "title": null,
        "url": "https://docs.xcrawl.com/doc/developer-guides/authentication/"
      }
    ],
    "endedAt": "2026-03-11T10:51:27.278040Z",
    "endpoint": "search",
    "job_id": "01KKE8BNMEKRHJB9GEWXPYQ8E1",
    "query": "site:docs.xcrawl.com XCrawl API",
    "request_id": "<request_id>",
    "search_id": "01KKE8BNMEKRHJB9GEWXPYQ8E1",
    "site_id": 26,
    "startedAt": "2026-03-11T10:51:24.710600Z",
    "status": "success",
    "success_num": 2,
    "uid": "<uid>",
    "username": "<username>",
    "version": ""
  },
  "started_at": "",
  "ended_at": "",
  "total_credits_used": 2
}