获取 Bing Ads 受众估算已完成任务

GET /v3/keywords_data/bing/audience_estimation/tasks_ready

本接口使用 GET 方法和以下路径：

GET /v3/keywords_data/bing/audience_estimation/tasks_ready

用于获取已完成但尚未领取的 Bing Ads 受众估算任务列表。使用标准任务提交方式且未设置 postback_url 时，可通过本接口获取已完成任务的 id，再使用对应的任务结果查询接口获取任务。

> 本接口返回尚未领取的任务。已领取的任务，或任务完成后三天未领取的任务，不会继续出现在列表中。

请求信息

请求方法：GET
请求路径：/v3/keywords_data/bing/audience_estimation/tasks_ready
完整 URL：https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/tasks_ready
认证方式：Bearer Token
请求体：无

请求头

请求头	类型	填	说明
`Authorization`	string	是	`Bearer smt_live_YOUR_KEY`
`Content-Type`	string	否	建议设置为 `application/json`

计费与调用限制

获取已完成任务列表不产生费用。
每个已完成任务会一直保留在列表中，直到被领取。
每分钟最多调用本接口 20 次。
每次调用最多返回过去三天完成的 1000 个任务。
任务完成三天仍未领取的，不会出现在列表中。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

使用 `postback_url` 时的注意事项

如果提交任务时指定了 postback_url，任务通常不会出现在本接口的已完成任务列表中。

当向回调服务器发送请求失败，且回调服务器返回的 HTTP 状态码小于 200 或大于 300 时，任务才可能出现在本列表中。对于高并发场景，建议优使用回调机制，并将本接口用于补偿查询失败的回调任务。

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	请求级状态码。错误码详见 `/v3/appendix/errors`
`status_message`	string	请求级提示信息
`time`	string	请求执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `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 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量
`path`	array	任务请求的 URL 路径信息
`data`	object	创建任务时提交到请求路径中的参数
`result`	array	已完成任务的结果列表

`tasks[].result` 字段

字段	类型	说明
`id`	string	已完成任务的唯一标识，UUID 格式
`se`	string	创建任务时指定的搜索引擎，通常为 `bing`
`function`	string	任务类型，通常为 `audience_estimation`
`date_posted`	string	任务提交时间，采用 UTC 格式
`endpoint`	string	用于获取该任务详细结果的 URL 路径

请求示例

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)
result = response.json()

if result.get("status_code") == 20000:
    print("已完成任务：")
    print(result)
else:
    print(
        "请求失败。错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

const response = await fetch(
  "https://api.seermartech.cn/v3/keywords_data/bing/audience_estimation/tasks_ready",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

const result = await response.json();

if (result.status_code === 20000) {
  // 处理已完成任务列表
  console.log(result.tasks);
} else {
  console.error(
    `请求失败。错误码：${result.status_code}，错误信息：${result.status_message}`
  );
}

响应示例

json

{
  "version": "0.1.20240801",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.3071 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2150 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "bing",
        "audience_estimation",
        "tasks_ready"
      ],
      "data": {
        "api": "keywords_data",
        "function": "audience_estimation",
        "se": "bing"
      },
      "result": [
        {
          "id": "01234567-89ab-cdef-0123-456789abcdef",
          "se": "bing",
          "function": "audience_estimation",
          "date_posted": "2024-08-01 12:00:00 +00:00",
          "endpoint": "/v3/keywords_data/bing/audience_estimation/task_get/01234567-89ab-cdef-0123-456789abcdef"
        }
      ]
    }
  ]
}

使用建议

定时轮询本接口时，应遵守每分钟 20 次的调用限制。
单次调用最多处理 1000 个任务，数量时应在后续轮询中继续获取。
高吞吐任务建议使用 postback_url 接收结果，减少轮询延迟和请求压力。
建议根据 status_code 和 status_message 实现异常处理与重试机制。
获取任务 id 后，应调用 endpoint 指向的任务结果接口领取详细结果。

实用场景

轮询未设置回调地址的受众估算任务，集中获取已完成任务 ID，便于批量领取结果并降低任务管理成本。
补偿处理失败的回调任务，定期检查未成功推送的任务，受众规模数据遗漏。
构建任务调度看板，统计领取、已完成和异常任务数量，帮助运营团队监控数据处理进度。
批量同步 Bing 受众估算结果，将完成任务接或广告投放分析流程，评估潜在受众规模。
控制高并发轮询频率，接口限制分批获取任务，减少触发限流并提升系统稳定性。

获取 Bing Ads 受众估算已完成任务 ​

请求信息 ​

请求头 ​

计费与调用限制 ​

使用 postback_url 时的注意事项 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

tasks[].result 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

使用建议 ​

实用场景 ​