获取已完成的 Bing Audience Estimation 任务列表

接口说明

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

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

请注意：由于平台 API 的任务队列存在短暂更新延迟，高并发场景下可能不会实时返回最新完成任务。如果你的系统需要每分钟拉取 1000 个任务，建议优使用 pingback/postback 机制；本接口更适合用于补偿性拉取，例如获取 postback 回调失败 的任务 ID。

接口地址

GET /v3/keywords_data/bing/audience_estimation/tasks_ready

完整请求地址：

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

计费与调用限制

获取已完成任务列表不会额外扣费
每个未拉取的任务会一直保留在列表中，直到结果被成功采集
最多每分钟调用 20 次
每次调用最多返回过去 3 天完成的 1000 个任务
以下任务不会出现在列表中：
已经被拉取过结果的任务
完成后 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	本次请求总成本，单位 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	已完成任务列表

`result` 数组中的字段

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

请求示例

cURL

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/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

typescript

import axios from "axios";

axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/tasks_ready",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 const result = response.data;
 // 在这里处理已完成任务列表
 console.log(result);
 })
 .catch((error) => {
 console.log(error);
 });

响应示例

json

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

错误处理说明

你需要重点以下两层状态：

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

建议处理方式：

判断顶层 status_code 是否为 20000
再遍历 tasks，检查每个任务是否执行成功
从 result 中提取已完成任务的 id
使用返回的 endpoint 或对应 Task GET 接口继续拉取任务结果

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

/v3/appendix/errors

使用建议

如果你依赖轮询方式采集结果，建议控制轮询频率，每分钟 20 次限制
如果任务量较大，建议优 postback_url，通过回调接收结果完成通知
对回调失败的任务，可定期调用本接口进行补拉
若需保证任务不遗漏，建议保存已拉取任务 ID，并建立补偿机制

实用场景

补拉回调失败任务：当异步回调因网络抖动或服务异常失败时，使用本接口重新获取任务 ID，结果丢失
批量轮询已完成任务：对未启用 postback_url 的任务定时轮询完成列表，集中获取结果，提高任务处理自动化程度
构建任务结果采集队列：通过本接口获取拉取任务，再将 endpoint 分发到处理，提升大批量结果采集效率
排查任务漏收问题：核对最近 3 天已完成但未采集的任务，定位结果消费链路中的异常环节
监控异步任务健康度：结合 tasks_error、任务状态码和完成数量，监控 Bing Audience Estimation 异步任务的执行与回收

获取已完成的 Bing Audience Estimation 任务列表 ​

接口说明 ​

接口地址 ​

计费与调用限制 ​

返回结果 ​

顶层字段 ​

tasks 数组中的字段 ​

result 数组中的字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理说明 ​

使用建议 ​

实用场景 ​