Web Scraper API – 获取结果

查询任务的采集进度、失败原因和结果下载链接。无论任务以同步还是异步模式创建，都可以通过此接口查询。

GET /v1/web-scraper/task/detail

快速开始 #

使用创建任务返回的 task_id 发起查询。请替换示例中的 API 地址、API Key 和任务 ID。

curl --request GET 'https://data.clawoxy.com/v1/web-scraper/task/detail?task_id=<TASK_ID>' \
  --header 'Authorization: Bearer <API_KEY>'

采集成功后，返回 HTTP 200，并提供下载链接。以下为示例数据：

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "01a0576790007a81b21db0d8b61eaabc",
    "template_code": "amazon_product_by_url",
    "mode": "async",
    "status": "succeeded",
    "result_status": "available",
    "error": null,
    "result": null,
    "result_url": "https://example.com/results/example-task.json?signature=SIGNATURE_PLACEHOLDER",
    "result_url_expires_at": 1788176412,
    "created_at": 1788172800,
    "completed_at": 1788172812,
    "result_expires_at": 1788432012
  }
}

使用 result_url 下载 JSON 结果：

curl '<RESULT_URL>' --output result.json

将 <RESULT_URL> 替换为响应中的完整链接。下载时不需要附加 API Key，请勿公开分享链接。

请求参数 #

请求头 #

请求头	必填	说明
Authorization	是	填写 Bearer <API_KEY>

查询参数 #

参数	类型	必填	说明
task_id	string	是	创建接口返回的任务 ID

将 task_id 放在请求 URL 的 ?task_id= 后面，无需提交请求体。

只能查询当前账户的任务。同一账户下的其他有效 API Key 也可以使用；其他账户的 API Key 无法查询该任务。

响应字段 #

查询成功时返回 HTTP 200。这仅表示已获取到任务信息，采集是否完成请查看 data.status。

字段	类型	说明
code	integer	0 表示查询成功，其他值见错误码说明
message	string	查询成功时为 success，查询失败时为英文错误说明
data	object 或 null	任务信息；查询失败时为 null

data 包含以下字段：

字段	类型	说明
task_id	string	任务 ID
template_code	string	任务使用的模板代码
mode	string	创建任务时选择的 sync 或 async
status	string	任务状态，见下表
result_status	string	结果是否可获取，见下表
error	object 或 null	任务失败原因，包含 code 和 message；未失败时为 null
result	null	此接口不直接返回采集数据，请通过下载链接获取
result_url	string 或 null	JSON 结果下载链接；尚未成功或结果已过期时为 null
result_url_expires_at	integer 或 null	当前下载链接的到期时间；没有链接时为 null
created_at	integer	任务创建时间
completed_at	integer 或 null	任务完成时间；尚未完成时为 null
result_expires_at	integer 或 null	结果保留截止时间；尚未成功或任务失败时为 null

时间字段均为秒级 Unix 时间戳。

根据任务状态获取结果 #

status	result_status	含义	下一步
queued	not_ready	排队中	稍后继续查询
running	not_ready	采集中	稍后继续查询
succeeded	available	采集成功	下载 result_url 中的结果
succeeded	expired	结果已过期	无法再获取该任务的结果
failed	unavailable	采集失败	查看 error 中的原因

建议每隔 2～5 秒查询一次，采集完成或失败后停止查询。不需要为了刷新进度再次创建任务。

下载得到的是模板对应的 JSON 数据，具体字段请查看模板说明。详情接口的 result 始终为 null，即使任务以同步模式创建，也需要使用 result_url 下载。

下载链接过期了怎么办？ #

查看两个到期时间：

• result_url_expires_at 是当前链接的有效期。链接过期后，结果仍在保留期内的，可以重新查询详情获取新链接。
• result_expires_at 是结果保留截止时间。到期后，result_status 为 expired，无法通过刷新链接恢复结果。

请以响应中的到期时间为准，及时下载并保存数据。重复查询不会延长结果保留时间。结果过期后，任务仍显示为 succeeded，表示这次采集曾经成功。

错误处理 #

查询未成功 #

当 code 不为 0 时，请根据错误码处理。例如，任务不存在或不属于当前账户时，返回 HTTP 404：

{
  "code": 120503,
  "message": "Task not found.",
  "data": null
}

错误码	HTTP	原因	建议操作
100301	400	任务 ID 缺失或格式不正确	使用创建接口返回的完整任务 ID
120102	401	API Key 缺失或无效	检查 API Key 和 Authorization 请求头
120103	403	API Key 已停用	确认 API Key 状态
120104	500	API Key 状态异常	联系客服协助处理
120405	503	服务暂时不可用	稍后使用同一个任务 ID 重试查询
120503	404	任务不存在或无权访问	检查任务 ID 和 API Key 所属账户

查询失败不代表采集失败，也不需要重新创建任务。需要帮助时，可向客服提供任务 ID、请求时间和响应头中的 X-Request-Id，请勿提供完整 API Key 或下载链接。

查询成功，但任务采集失败 #

此时 HTTP 状态仍为 200、code 仍为 0，但 data.status 为 failed。失败原因在 data.error 中，例如：

{
  "code": 120404,
  "message": "任务执行超时。"
}

data.error.code	含义	建议操作
120403	采集失败或未获得有效结果	检查目标网址和模板参数后，再决定是否重新采集
120404	采集超时	稍后按需重新采集

任务失败后无需继续查询进度。需要重新采集时，可创建新任务。