获取已完成任务列表（keywords_data/tasks_ready）

接口说明

该接口用于返回已完成但尚未被获取结果的任务列表。

如果你使用标准提交方式，且未设置 postback_url，可以通过本接口获取所有已完成任务的 id，再调用对应的 Task GET 结果接口拉取详细数据。

适用于以下型流程：

1. 提交数据任务；
2. 定期轮询 /v3/keywords_data/google/v2/tasks_ready；
3. 获取已完成任务的 id；
4. 根据返回的 endpoint 或任务 id 调用结果接口获取任务明细。

注意： 由于平台 API 的任务完成队列存在轻微延迟，高并发场景下可能无法做到实时同步。 如果你的系统需要每分钟采集 1000 个任务，建议优使用 pingback/postback 回调机制；本接口更适合用于补偿拉取，例如获取回调失败的任务 ID。

请求地址

GET https://api.seermartech.cn/v3/keywords_data/google/v2/tasks_ready

计费说明

获取已完成任务列表不额外收费，响应中的 cost 通常为 0。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

使用限制

• 每分钟最多可调用 20 次
• 单次调用最多返回 1000 个任务
• 返回最近 3 天完成、且尚未被获取结果的任务
• 已经成功拉取过结果的任务，不会再出现在列表中
• 任务完成后 3 天未拉取，也不会再出现在列表中

postback_url 行为说明

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

例外是：本平台向你的服务器发送回调失败时，该任务仍可能出现在列表中。通常指你的服务端返回的 HTTP 状态码：

• 小于 200
• 大于 300

因此，本接口也常用于补偿处理回调失败任务。

响应结构

接口返回 JSON 数据，顶层 tasks 数组，数组中为本次请求对应的任务信息。

顶层字段说明

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

建议在接时完善异常处理逻辑，覆盖状态码异常、空结果、限、任务失败等。

tasks[] 字段说明

字段名	类型	说明
id	string	当前请求任务的唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行时间，单位秒
cost	float	该任务成本
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	请求 URL 中传的参数
result	array	已完成任务列表

tasks[].result[] 字段说明

字段名	类型	说明
id	string	已完成任务的唯一标识，UUID 格式
se	string	创建任务时指定的搜索引擎
function	string	任务类型
date_posted	string	任务提交时间，UTC 格式
tag	string	自定义任务标识
endpoint	string	用于拉取该任务结果的接口地址

请求示例

cURL

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

Python

import requests

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

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

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

TypeScript

import axios from "axios";

// 获取最近已完成但尚未拉取的任务列表
async function getTasksReady {
 const response = await axios.get(
 "https://api.seermartech.cn/v3/keywords_data/google/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.error(`error. Code: ${result.status_code} Message: ${result.status_message}`);
 }
}

getTasksReady.catch(console.error);

响应示例

{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1927 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "v2",
 "se": "google"
 },
 "result": []
 }
 ]
}

返回结果解读

当请求成功时：

• status_code = 20000 表示接口调用成功；
• tasks[].result 中已完成但尚未被获取结果的任务；
• 每个结果对象中的 endpoint 可直接用于后续拉取任务结果；
• 若 result 为空，通常表示当前没有符合条件的拉取任务。

错误处理建议

建议重点处理以下：

• 接口状态异常：判断顶层 status_code 是否为 20000
• 任务级错误：检查 tasks_error 是否大于 0
• 空结果：tasks[].result 为空时，不应视为失败
• 频率限：每分钟 20 次调用限制
• 补偿回调失败任务：若已 postback_url，可将本接口作为回调失败后的底机制

对接建议

如果你的系统采用轮询方式，建议：

• 每隔固定时间调用一次本接口；
• 保存已处理过的任务 id，重复消费；
• 获取 endpoint 后立即获取结果；
• 对 3 天未拉取的任务建立补偿或告警机制；
• 高吞吐场景优使用回调模式，本接口用于补漏。

实用场景

• 轮询已完成任务：定期获取最近完成的任务 ID，构建稳定的异步采集工作流。
• 补拉回调失败结果：当 postback_url 回调失败时，通过本接口找回遗漏任务，数据丢失。
• 批量调度结果抓取：一次获取最多 1000 个已完成任务，适合批量触发下游结果库流程。
• 监控任务产出效率：结合 date_posted 和完成列表，评估任务完成延迟与系统吞吐表现。
• 构建任务补偿机制：对未及时拉取或处理失败的任务进行二次扫描，提高 SEO 数据链路稳定性。