获取 Bing 搜索量历史已完成任务列表

接口说明

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

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

如需了解任务完成机制与已完成任务列表的获取方式，可参考文档中心说明。

注意： 由于平台 API 的队列更新存在轻微延迟，高并发场景下可能会受到影响。 如果你的系统需要每分钟处理 1000 个任务结果，建议优使用 pingback/postback 机制，并将 tasks_ready 用于补拉那些 postback 失败的任务 ID。

请求地址

GET /v3/keywords_data/bing/search_volume_history/tasks_ready

完整请求 URL：

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

计费说明

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

• 每个未拉取的任务会保留在列表中，直到结果被成功获取
• 每分钟最多可发起 20 次 API 调用
• 每次调用最多返回 1000 个任务
• 返回最近 3 天完成且尚未被拉取的任务
• 已被拉取的任务不会再次出现在列表中
• 完成后 3 天仍未拉取的任务，也不会出现在列表中

如果设置了 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	本次请求总费用，USD；该接口通常为 0，扣费以响应头 X-SeerMarTech-Charge-CNY 为准
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	当前任务费用，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	用于拉取该任务结果的接口地址

使用说明

型流程如下：

1. 提交 Bing 搜索量历史任务
2. 轮询 /v3/keywords_data/bing/search_volume_history/tasks_ready
3. 获取已完成任务的 id
4. 根据 result[].endpoint 或对应 Task GET 接口获取结果

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/keywords_data/bing/search_volume_history/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/search_volume_history/tasks_ready"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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

TypeScript

import axios from "axios";

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

 console.log(response.data);
}

getTasksReady.catch(console.error);

响应示例

{
 "version": "0.1.20240626",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1358 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_data",
 "function": "search_volume_history",
 "se": "bing"
 },
 "result": []
 }
 ]
}

状态码与异常处理

建议对以下两类状态进行完整处理：

• 接口级状态：顶层 status_code、status_message
• 任务级状态：tasks[].status_code、tasks[].status_message

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

• /v3/appendix/errors

建议在生产环境中实现：

• 重试机制
• 空结果处理 -时与限流控制
• postback 失败补拉逻辑

注意事项

• 本接口只返回已完成但未拉取的任务
• 只覆盖最近 3 天的已完成任务
• 每次最多返回 1000 个任务
• 调用频率上限为每分钟 20 次
• 如果你已经启用了 postback_url，通常无需频繁轮询该接口
• 对于高吞吐业务，建议使用回调模式代替纯轮询模式

实用场景

• 轮询补拉结果：定时获取最近完成但尚未拉取的 Bing 搜索量历史任务，确保异步任务结果不遗漏。
• 补偿回调失败任务：当业务系统的 postback 接收失败时，通过该接口找回任务 ID，数据丢失。
• 构建任务消费队列：取回已完成任务列表，再按 endpoint 批量拉取明细结果，提升异步采集链路稳定性。
• 监控任务产出时效：结合 date_posted 统计任务从提交到完成的延迟，评估数据生产效率。
• 业务标签追踪任务：通过 tag 将完成任务映射到项目、客户或批次，便于 SEO 数据归档与审计。