获取已完成的 SERP 任务列表

接口说明

Tasks Ready 接口用于获取已执行完成但尚未被获取结果的任务列表。

如果你使用标准提交方式，且未指定 postback_url，可以通过本接口拿到所有已完成任务的 id，随后再调用对应的 Task GET 接口拉取任务结果。

如需按搜索引擎和类型获取任务列表，可使用以下容路径：

• GET /v3/serp/wp/v2/tasks_ready
• GET /v3/serp/$se/tasks_ready
• GET /v3/serp/tasks_ready

说明：

• $se 表示搜索引擎名称
• wp、v2 为示例，可替换为对应支持的搜索引擎与类型

完整请求地址示例：

https://api.seermartech.cn/v3/serp/wp/v2/tasks_ready

使用建议

由于平台 API 的任务完成队列存在轻微刷新延迟，高并发场景下可能无法做到实时无缝获取。

如果你的系统需要每分钟处理 1000 个任务，建议：

• 优使用 pingback / postback 机制接收任务完成通知
• 将 Tasks Ready 接口主要用于补拉postback 回调失败的任务 ID

计费说明

获取已完成任务列表不会产生费用。

• 参考价约 ¥0.0000 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

调用限制

• 最多每分钟调用 20 次
• 每次调用最多返回过去 3 天完成的 1000 个任务
• 任务会一直保留在列表中，直到结果被成功拉取
• 以下任务不会出现在列表中：
• 已经完成结果拉取的任务
• 完成后 3 天未拉取 的任务

postback_url 的行为

如果你在创建任务时指定了 postback_url，该任务通常不会出现在已完成任务列表中。

当以下发生时，该任务才可能该列表：

• 平台向你的服务器发送回调失败
• 你的服务器返回的 HTTP 状态码小于 200 或大于 300

请求方式

HTTP Request

GET /v3/serp/wp/v2/tasks_ready

请求头

名称	类型	填	说明
Authorization	string	是	认证令牌，格式：Bearer smt_live_YOUR_KEY
Content-Type	string	否	建议使用 application/json

这是 GET 接口，无需请求体。

响应结构

接口返回 JSON 数据，顶层 tasks 数组，每个表示一次接口调用任务的执行结果。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表见 /v3/appendix/errors
status_message	string	通用状态信息，完整列表见 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

建议在生产环境中基于 status_code 与 status_message 做统一异常处理。

tasks[] 字段

字段	类型	说明
id	string	当前请求任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000–60000，完整列表见 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	请求 URL 中携带的参数
result	array	已完成任务列表

tasks[].data 字段

字段	类型	说明
api	string	API 模块，示例：serp
function	string	当前功能，示例：tasks_ready
se	string	搜索引擎标识
se_type	string	搜索引擎类型，示例：v2

tasks[].result[] 字段

字段	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎
se_type	string	搜索引擎类型，例如 v2
date_posted	string	任务提交时间，UTC 格式
tag	string	用户自定义任务标识
endpoint_regular	string	获取 SERP Regular 结果的 URL；若当前端点不支持，则为 null
endpoint_advanced	string	获取 SERP Advanced 结果的 URL；若当前端点不支持，则为 null
endpoint_html	string	获取 SERP HTML 结果的 URL；若当前端点不支持，则为 null

调用示例

curl

curl --location --request GET "https://api.seermartech.cn/v3/serp/wp/v2/tasks_ready" \
 --header "Authorization: Bearer smt_live_YOUR_KEY" \
 --header "Content-Type: application/json"

Python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/tasks_ready"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
result = response.json

if result.get("status_code") == 20000:
 print(result)
else:
 print(f"error. Code: {result.get('status_code')} Message: {result.get('status_message')}")

TypeScript

import axios from "axios";

async function getTasksReady {
 try {
 const response = await axios.get(
 "https://api.seermartech.cn/v3/serp/wp/v2/tasks_ready",
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 const result = response.data;

 if (result.status_code === 20000) {
 console.log(result);
 } else {
 console.log(
 `error. Code: ${result.status_code} Message: ${result.status_message}`
 );
 }
 } catch (error) {
 console.error(error);
 }
}

getTasksReady;

响应示例

{
 "version": "0.1.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2270 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "tasks_ready",
 "se": "wp",
 "se_type": "v2"
 },
 "result": []
 }
 ]
}

错误处理

请重点以下字段：

• 顶层 status_code：表示本次接口调用是否成功
• 顶层 status_message：返回整体状态说明
• tasks[].status_code：表示单个任务处理状态
• tasks[].status_message：表示单个任务的详细说明

完整错误码与状态说明可参考：

• /v3/appendix/errors

结果获取流程建议

型处理流程如下：

1. 提交 SERP 任务
2. 轮询 Tasks Ready 接口，获取已完成任务 ID
3. 从 result[] 中读取每个已完成任务的 id
4. 使用返回的 endpoint_regular、endpoint_advanced 或 endpoint_html 获取结果
5. 对已获取结果的任务做去重与归档，重复消费

实用场景

• 轮询已完成任务：在未回调通知时，定期获取已完成任务 ID，确保批量 SERP 采集结果能够被及时拉取。
• 补偿失败回调任务：当业务系统的 postback 接收异常时，通过本接口找回漏接的任务，降低结果丢失风险。
• 构建结果拉取队列：用本接口获取消费任务，再按 endpoint_regular / endpoint_advanced / endpoint_html 分发到不同处理管道。
• 监控任务完成效率：结合 date_posted 与任务返回时间，评估任务从提交到完成的延迟，优化采集调度策略。
• 理积压任务：定期扫描过去 3 天尚未拉取的已完成任务，任务时后无法再获取结果。