获取 Bing URL 建议已完成任务

本接口使用 GET 方法，请求路径为：

/v3/keywords_data/bing/keyword_suggestions_for_url/tasks_ready

用于获取已完成但尚未领取的 Bing URL 建议任务列表。使用标准任务提交方式且未设置 postback_url 时，可通过本接口获取已完成任务的 id，再调用对应的任务结果获取接口领取结果。

> 已完成任务队列可能存在短暂延迟。若系统需要每分钟领取 1000 个任务，建议优使用回调方式接收结果，并将本接口用于获取回调失败任务的 ID。

请求信息

请求方法：GET
请求地址：https://api.seermartech.cn/v3/keywords_data/bing/keyword_suggestions_for_url/tasks_ready
认证方式：Bearer Token
请求体：无
返回格式：JSON

计费与调用限制

获取已完成任务列表不产生费用。
每个任务在被领取前都会持续保留在列表中。
每分钟最多调用 20 次。
每次调用最多返回过去 3 天完成的 1000 个任务。
已领取的任务不会再次出现在列表中。
完成后 3 天仍未领取的任务将从列表中移除。
如果提交任务时设置了 postback_url，任务通常不会出现在本接口返回列表中。
当向回调地址发送请求失败，且对方返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能出现在已完成任务列表中。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应字段

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	请求级状态码
`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` 范围
`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	任务类型，此处为 `keyword_suggestions_for_url`
`date_posted`	string	任务提交时间，采用 UTC 格式
`tag`	string	用户自定义任务标识
`endpoint`	string	用于领取该任务结果的接口地址

请求示例

cURL

bash

curl --location --request GET \
  "https://api.seermartech.cn/v3/keywords_data/bing/keyword_suggestions_for_url/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/keyword_suggestions_for_url/tasks_ready"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

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

if response.status_code == 200:
    result = response.json()
    if result.get("status_code") == 20000:
        # 处理已完成任务列表
        print(result)
    else:
        print(
            "请求失败，状态码：%s，说明：%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 请求失败：%s" % response.status_code)

TypeScript

typescript

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/keywords_data/bing/keyword_suggestions_for_url/tasks_ready",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      // 处理已完成任务列表
      console.log(result);
    } else {
      console.error(
        `请求失败，状态码：${result.status_code}，说明：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("请求异常：", error);
  });

响应示例

json

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

状态码处理

请在客户端实现完善的异常处理机制，同时检查以下字段：

HTTP 状态码，用于判断网络层请求是否成功。
顶层 status_code，用于判断本次接口调用是否成功。
tasks[].status_code，用于判断单个已完成任务是否可正常领取。
status_message，用于记录或展示错误原因。

当顶层 status_code 为 20000 时，表示请求成功。成功响应中的 tasks 可能为空数组，表示当前没有可领取的已完成任务。

实用场景

轮询未设置回调的已完成任务：定期获取任务 ID 并领取建议结果，适用于无法部署回调接收服务的系统。
补偿回调失败任务：识别回调投递失败后重新队列的任务，降低数据丢失风险。
构建任务领取队列：按任务完成状态批量拉取任务并交给后续处理流程，提高 SEO 数据采集效率。
监控建议任务积压：统计领取任务数量和错误数量，及时发现采集链路延迟或异常。
管理多站点研究流程：结合 tag 区分不同网站、项目或客户，便于将完成结果准确分发到对应业务。

获取 Bing URL 建议已完成任务 ​

请求信息 ​

计费与调用限制 ​

响应字段 ​

顶层字段 ​

tasks 数组字段 ​

tasks[].result 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码处理 ​

实用场景 ​