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/jsonAuthorization: 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 includesdescription,position,title, andurlstatus: provider-side status, such assuccessstartedAt/endedAt: provider-side timestampscredits_used: credits usedcredits_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
}