XCrawl Search
Overview
This skill uses XCrawl Search API to retrieve query-based results.
Default behavior is raw passthrough: return upstream API response bodies as-is.
Required Local Config
Before using this skill, the user must create a local config file and write XCRAWL_API_KEY into it.
Path: INLINECODE1
CODEBLOCK0
Read API key from local config file only. Do not require global environment variables.
Credits and Account Setup
Using XCrawl APIs consumes credits.
If the user does not have an account or available credits, guide them to register at https://dash.xcrawl.com/.
After registration, they can activate the free 1000 credits plan before running requests.
Tool Permission Policy
Request runtime permissions for curl and node only.
Do not request Python, shell helper scripts, or other runtime permissions.
API Surface
- - Search endpoint: INLINECODE6
- Base URL: INLINECODE7
- Required header: INLINECODE8
Usage Examples
cURL
CODEBLOCK1
Node
CODEBLOCK2
Request Parameters
Request endpoint and headers
- - Endpoint: INLINECODE9
- Headers:
- INLINECODE10
- INLINECODE11
Request body: top-level fields
| Field | Type | Required | Default | Description |
|---|
| INLINECODE12 | string | Yes | - | Search query |
| INLINECODE13 |
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 Parameters
| Field | Type | Description |
|---|
| INLINECODE20 | string | Task ID |
| INLINECODE21 |
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 |
INLINECODE31 notes from current API reference:
- - Concrete result schema is implementation-defined
- Includes billing fields like
credits_used and INLINECODE33
Workflow
- 1. Rewrite the request as a clear search objective.
- - Include entity, geography, language, and freshness intent.
- 2. Build and execute
POST /v1/search.
- - Keep request explicit and deterministic.
- 3. Return raw API response directly.
- - Do not synthesize relevance summaries unless requested.
Output Contract
Return:
- - Endpoint used (
POST /v1/search) - INLINECODE36 used for the request
- Raw response body from search call
- Error details when request fails
Do not generate summaries unless the user explicitly requests a summary.
Guardrails
- - Do not claim ranking guarantees that the API does not expose.
- Do not fabricate unavailable filters or response fields.
- Do not hardcode provider-specific tool schemas in core logic.
XCrawl 搜索
概述
此技能使用 XCrawl 搜索 API 获取基于查询的结果。
默认行为为原始透传：按原样返回上游 API 响应体。
所需本地配置
使用此技能前，用户必须创建本地配置文件并在其中写入 XCRAWLAPIKEY。
路径：~/.xcrawl/config.json
json
{
XCRAWLAPIKEY: apikey>
}
仅从本地配置文件读取 API 密钥。无需全局环境变量。
积分与账户设置
使用 XCrawl API 会消耗积分。
如果用户没有账户或可用积分，请引导他们前往 https://dash.xcrawl.com/ 注册。
注册后，他们可以在运行请求前激活免费的 1000 积分套餐。
工具权限策略
仅请求 curl 和 node 的运行时权限。
不请求 Python、shell 辅助脚本或其他运行时权限。
API 接口
- - 搜索端点：POST /v1/search
- 基础 URL：https://run.xcrawl.com
- 必需标头：Authorization: Bearer APIKEY>
使用示例
cURL
bash
APIKEY=$(node -e const fs=require(fs);const p=process.env.HOME+/.xcrawl/config.json;const k=JSON.parse(fs.readFileSync(p,utf8)).XCRAWLAPI_KEY||;process.stdout.write(k))
curl -sS -X POST https://run.xcrawl.com/v1/search \
-H Content-Type: application/json \
-H Authorization: Bearer ${API_KEY} \
-d {query:AI web crawler API,location:US,language:en,limit:20}
Node
bash
node -e
const fs=require(fs);
const apiKey=JSON.parse(fs.readFileSync(process.env.HOME+/.xcrawl/config.json,utf8)).XCRAWLAPIKEY;
const body={query:web scraping pricing,location:DE,language:de,limit:30};
fetch(https://run.xcrawl.com/v1/search,{
method:POST,
headers:{Content-Type:application/json,Authorization:Bearer ${apiKey}},
body:JSON.stringify(body)
}).then(async r=>{console.log(await r.text());});
请求参数
请求端点和标头
- - 端点：POST https://run.xcrawl.com/v1/search
- 标头：
- Content-Type: application/json
- Authorization: Bearer
请求体：顶层字段
| 字段 | 类型 | 必需 | 默认值 | 描述 |
|---|
| query | 字符串 | 是 | - | 搜索查询 |
| location |
字符串 | 否 | US | 位置（国家/城市/地区名称或 ISO 代码；尽力匹配） |
| language | 字符串 | 否 | en | 语言（ISO 639-1） |
| limit | 整数 | 否 | 10 | 最大结果数（1-100） |
响应参数
| 字段 | 类型 | 描述 |
|---|
| search_id | 字符串 | 任务 ID |
| endpoint |
字符串 | 始终为 search |
| version | 字符串 | 版本 |
| status | 字符串 | completed |
| query | 字符串 | 搜索查询 |
| data | 对象 | 搜索结果数据 |
| started_at | 字符串 | 开始时间（ISO 8601） |
| ended_at | 字符串 | 结束时间（ISO 8601） |
| total
creditsused | 整数 | 使用的总积分 |
来自当前 API 参考的 data 说明：
- - 具体结果模式由实现定义
- 包含计费字段，如 creditsused 和 creditsdetail
工作流程
- 1. 将请求重写为清晰的搜索目标。
- 2. 构建并执行 POST /v1/search。
- 3. 直接返回原始 API 响应。
输出约定
返回：
- - 使用的端点（POST /v1/search）
- 用于请求的 request_payload
- 搜索调用的原始响应体
- 请求失败时的错误详情
除非用户明确要求摘要，否则不生成摘要。
防护措施
- - 不声称 API 未公开的排名保证。
- 不虚构不可用的过滤器或响应字段。
- 不在核心逻辑中硬编码特定提供商的工具模式。
