获取已完成任务列表

GET /v3/keywords_data/bing/v2/tasks_ready

接口说明

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

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

如需了解任务完成机制与完成任务列表的获取方式，可参考帮助文档。

注意：

• 由于平台 API 的架构特性，已完成任务队列会有轻微延迟。
• 如果你的系统需要每分钟拉取 1000 个任务，建议优使用 pingback / postback 回调机制。
• 本接口更适合用于补偿拉取，例如：获取回调失败的任务 ID。

如果任务提交时指定了 postback_url，该任务通常不会出现在已完成任务列表中。只有在回调请求发送到你的服务器失败，且你的服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在本接口返回的列表中。

---

请求方式

GET /v3/keywords_data/bing/v2/tasks_ready

完整地址：

https://api.seermartech.cn/v3/keywords_data/bing/v2/tasks_ready

---

计费与调用限制

• 获取已完成任务列表不额外收费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 每分钟最多可调用 20 次
• 每次调用最多返回最近 3 天完成的 1000 个任务
• 已经成功获取结果的任务，不会再次出现在列表中
• 完成后** 3 天仍未拉取**的任务，也不会再出现在列表中

---

返回结构说明

接口返回 JSON 数据，顶层 tasks 数组记录本次查询到的任务信息。

顶层字段

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

建议在接时完善异常处理和状态码处理逻辑。

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[].result[] 字段

字段名	类型	说明
id	string	已完成任务的任务 ID，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/bing/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/bing/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";

axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/keywords_data/bing/v2/tasks_ready",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
})
 .then((response) => {
 // 返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(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": "bing"
 },
 "result": []
 }
 ]
}

---

使用建议

1. 轮询频率控制 本接口每分钟最多调用 20 次，建议结合业务量设置合理的轮询间隔，触发频控。

2. 优使用回调机制 如果你的任务量较大，建议在创建任务时 postback_url，通过回调接收结果完成通知，减少轮询压力。

3. 用于失败补偿更合适 对于已经启用回调的系统，可将本接口作为回调失败后的补偿拉取，定期检查遗漏任务。

4. 及时获取结果 已完成任务保留在列表中 3 天，建议尽快根据返回的 endpoint 或任务 id 拉取详细结果。

---

错误处理

可重点以下字段：

• status_code：接口整体状态码
• status_message：接口整体状态描述
• tasks_error：本次返回中异常任务数量
• tasks[].status_code：单个任务状态码
• tasks[].status_message：单个任务状态信息

完整错误码说明可参考 /v3/appendix/errors。

---

实用场景

• 补拉回调失败任务：当任务回调因网络波动或服务异常失败时，定期查询已完成任务列表，结果漏收。
• 构建结果拉取队列：批量获取已完成任务 ID，再分发到下游调用 Task GET，提高结果处理吞吐。
• 监控任务完成率：结合任务提交记录与本接口返回结果，评估任务完成速度与系统稳定性。
• 理积压任务：识别近 3 天尚未拉取的已完成任务，及时补采结果，减少数据丢失风险。
• 定位回调链路问题：对比启用 postback_url 的任务是否出现在列表中，快速发现回调失败或服务端状态码异常。