Search API

Overview

POST /v1/search retrieves search results using keyword, location, and language parameters.

Request

Endpoint

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

Headers

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

Request body

Top-level fields

Field	Type	Required	Default	Description
`query`	string	Yes	-	Search query
`location`	string	No	`US`	Location (country/city/region name or ISO code; best effort)
`language`	string	No	`en`	Language (ISO 639-1)
`limit`	integer	No	`10`	Max results (1-100)

Response

Field	Type	Description
`search_id`	string	Task ID
`endpoint`	string	Always `search`
`version`	string	Version
`status`	string	`completed`
`query`	string	Search query
`data`	object	Search result data
`started_at`	string	Start time (ISO 8601)
`ended_at`	string	End time (ISO 8601)
`total_credits_used`	integer	Total credits used

data notes:

data.data: search result list; each item includes description, position, title, and url
status: provider-side status, such as success
startedAt / endedAt: provider-side timestamps
credits_used: credits used
credits_detail: credit breakdown

Examples

Request example

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

Response example

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