获取已完成任务列表（V2）

GET /v3/appendix/errors

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

GET https://api.seermartech.cn/v3/keywords_data/wp/v2/tasks_ready

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

> 注意：原始文档标题为 keywords_data/google_ads/tasks_ready，但接口路径为 /v3/keywords_data/wp/v2/tasks_ready。请以本文列出的请求路径为准。

计费与调用限制

• 获取已完成任务列表本身不产生费用。
• 每个任务在被领取前都会保留在列表中。
• 每分钟最多调用本接口 20 次。
• 每次调用最多返回过去三天完成的 1000 个任务。
• 已经领取结果的任务不会再次出现在列表中。
• 任务完成后三天未领取的任务将从列表中移除。
• 如果创建任务时设置了 postback_url，任务通常不会出现在本列表中。
• 只有当平台向你的服务器发送回调失败，且服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在列表中。
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

对于每分钟需要收集 1000 个任务的高并发场景，建议优使用回调或推送机制，并将本接口用于补偿查询失败的回调任务。

请求

请求头

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

本接口无需请求体。可通过 URL 路径中的版本及搜索引擎标识选择任务类型。

参数	类型	说明
v2	路径标识	获取 V2 任务列表
wp	路径标识	任务所属的搜索引擎或数据源标识

cURL 示例

curl --location --request GET \
  "https://api.seermartech.cn/v3/keywords_data/wp/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/wp/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(
        "请求失败，错误码：{}，错误信息：{}".format(
            data.get("status_code"),
            data.get("status_message"),
        )
    )

TypeScript 示例

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/keywords_data/wp/v2/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.message);
  });

响应说明

接口返回 JSON 数据 tasks 数组符合条件的已完成任务。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	请求级状态码。完整错误码列表请参考 /v3/appendix/errors
status_message	string	请求级提示信息。完整提示信息请参考 /v3/appendix/errors
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	创建任务时传 URL 的参数
result	array	任务结果数组

result 字段

字段	类型	说明
id	string	已完成任务的唯一标识，采用 UUID 格式
se	string	创建任务时指定的搜索引擎或数据源
function	string	任务类型
date_posted	string	任务提交时间，使用 UTC 格式
endpoint	string	用于领取任务结果的接口 URL

响应示例

{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1927 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1000 sec.",
      "cost": 0,
      "result_count": 0,
      "path": [
        "v3",
        "keywords_data",
        "wp",
        "v2",
        "tasks_ready"
      ],
      "data": {
        "api": "keywords_data",
        "function": "v2",
        "se": "wp"
      },
      "result": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "se": "wp",
          "function": "v2",
          "date_posted": "2024-01-01 00:00:00 +00:00",
          "endpoint": "/v3/keywords_data/wp/v2/tasks_ready"
        }
      ]
    }
  ]
}

错误处理建议

建议客户端至少处理以下：

1. 检查顶层 status_code 是否为 20000。
2. 检查 tasks_error 是否大于 0。
3. 对每个任务分别检查 status_code 和 status_message。
4. 根据 id 去重，重复领取同一任务。
5. 对暂时性网络错误和服务端错误执行带退避策略的重试。
6. 对三天仍未领取的任务做好任务丢失监控。
7. 不要高于每分钟 20 次的调用限制。

实用场景

• 轮询已完成任务：定期获取尚未领取的任务 ID，并批量拉取结果，降低异步任务处理的人工维护成本。
• 补偿失败回调：筛选回调请求失败的任务，重新获取任务结果， SEO 数据因回调异常丢失。
• 构建任务调度队列：根据 tasks_count 和任务状态安排结果领取，实现任务提交、完成检测和结果库的闭环。
• 监控任务处理延迟：结合 date_posted 和当前时间识别长时间未领取的任务，及时发现数据处理链路堵塞。
• 统计不同数据源任务完成：根据 se 和 function 汇总任务完成量与错误量，为 SEO 数据采集资源调度提供依据。