keywords_data/tasks_ready：获取已完成任务列表

GET /v3/appendix/errors

接口说明

本接口使用 GET 方法访问：

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

用于获取已完成但尚未领取结果的任务列表。

当您使用 Standard 提交方式且未设置 postback_url 时，可通过本接口获取所有已完成任务的 id，再使用对应的任务结果获取接口领取结果。

> 本接口返回任务信息，不收取额外费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

使用限制

每个任务在被领取前会持续保留在列表中。
每分钟最多调用 20 次。
每次调用最多返回过去 3 天完成的 1000 个任务。
已领取的任务不会再次出现在列表中。
完成后 3 天仍未领取的任务将从列表中移除。
如果任务设置了 postback_url，正常不会出现在本接口返回结果中。
只有当向您的服务器发送回调失败，且服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在已完成任务列表中。
由于系统架构原因，已完成任务队列可能存在少量延迟。对于每分钟需要领取 1000 个任务的场景，建议优使用 pingback/postback 机制；本接口可用于补获取回调失败任务的 ID。

请求示例

cURL

bash

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

PHP

php

<?php

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.seermartech.cn/v3/keywords_data/google/v2/tasks_ready',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    echo '请求失败：' . curl_error($ch);
} else {
    $result = json_decode($response, true);

    if (($result['status_code'] ?? null) === 20000) {
        print_r($result);
    } else {
        echo '错误码：' . ($result['status_code'] ?? '未知');
        echo '，错误信息：' . ($result['status_message'] ?? '未知');
    }
}

curl_close($ch);

TypeScript

typescript

import axios from 'axios';

axios.get(
  'https://api.seermartech.cn/v3/keywords_data/google/v2/tasks_ready',
  {
    headers: {
      Authorization: 'Bearer smt_live_YOUR_KEY',
      'Content-Type': 'application/json',
    },
  }
)
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error('请求失败：', error.response?.data || error.message);
  });

Python

python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/v2/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(result)
else:
    print(
        "错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

C#

csharp

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

namespace SeerMarTechDemos
{
    public static class Demos
    {
        public static async Task GetKeywordsDataTasksReady()
        {
            using var httpClient = new HttpClient();

            httpClient.DefaultRequestHeaders.Authorization =
                new AuthenticationHeaderValue("Bearer", "smt_live_YOUR_KEY");

            var response = await httpClient.GetAsync(
                "https://api.seermartech.cn/v3/keywords_data/google/v2/tasks_ready"
            );

            var result = await response.Content.ReadAsStringAsync();

            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine(result);
            }
            else
            {
                Console.WriteLine($"HTTP 请求失败：{response.StatusCode}");
                Console.WriteLine(result);
            }
        }
    }
}

响应结构

接口返回 JSON 数据，主要顶层任务统计信息和 tasks 数组。

json

{
  "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.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "v2",
        "tasks_ready"
      ],
      "data": {
        "api": "keywords_data",
        "function": "v2",
        "se": "google"
      },
      "result": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "se": "google",
          "function": "v2",
          "date_posted": "2024-01-01 12:00:00 +00:00",
          "tag": "example-task",
          "endpoint": "/v3/keywords_data/google/v2/task_get"
        }
      ]
    }
  ]
}

响应字段

顶层字段

字段	类型	说明
`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	请求路径信息
`data`	object	请求 URL 中传的参数
`result`	array	已完成任务列表

`tasks[].result` 数组字段

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

任务结果领取

获取任务 ID 后，请根据返回的 endpoint 调用对应的任务结果获取接口。不要直接将本接口中的 /v3/keywords_data/google/v2/tasks_ready 当作任务结果接口使用。

领取成功后，该任务将从已完成任务列表中移除。

状态码与异常处理

20000：请求成功。
状态码表示接口或任务处理异常。
建议客户端同时检查：
- HTTP 状态码；
- 顶层 status_code；
- tasks[].status_code；
- status_message；
- tasks_error 是否大于 0。

完整错误码列表请参 /v3/appendix/errors。

实用场景

轮询获取未设置回调地址的已完成任务：批量发现已完成任务并及时领取结果，任务长期滞留。
补偿回调失败任务：定期扫描已完成任务列表，找出回调投递失败的任务，降低数据丢失风险。
构建异步任务调度器：结合 tasks_count、tasks_error 和任务 endpoint，自动分结果领取与重试流程。
监控数据任务状态：通过 status_code 和 status_message 统计成功、失败及异常任务，提升 SEO 数据管道的可观测性。
控制高并发结果领取节奏：依据每分钟调用次数和单次最多返回任务数设计轮询策略，触发接口频率限制。

keywords_data/tasks_ready：获取已完成任务列表 ​

接口说明 ​

使用限制 ​

请求示例 ​

cURL ​

PHP ​

TypeScript ​

Python ​

C# ​

响应结构 ​

响应字段 ​

顶层字段 ​

tasks 数组字段 ​

tasks[].result 数组字段 ​

任务结果领取 ​

状态码与异常处理 ​

实用场景 ​