app_data/tasks_ready

GET /v3/app_data/tasks_ready

获取已完成任务列表

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

text

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

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

请求路径

获取指定搜索引擎的已完成任务：

text

GET https://api.seermartech.cn/v3/app_data/$se/tasks_ready

$se 为搜索引擎名称。

获取 App Data API 的已完成任务：

text

GET https://api.seermartech.cn/v3/app_data/tasks_ready

使用限制

获取任务列表不会产生额外费用。
每个任务会一直保留在列表中，直到被成功领取。
每分钟最多调用本接口 20 次。
每次调用最多返回最近 3 天完成的 1000 个任务。
任务完成 3 天仍未领取时，将从列表中移除。
已经领取过的任务不会再次出现在列表中。
如果创建任务时设置了 postback_url，任务通常不会出现在本接口的列表中。
只有当向回调地址发送请求失败，且目标服务器返回小于 200 或大于 300 的 HTTP 状态码时，该任务才可能出现在领取列表中。
完成任务队列可能存在少量更新延迟。对于每分钟需要领取 1000 个任务的高并发场景，建议优使用回调机制，并将本接口作为获取回调失败任务 ID 的补手段。

计费说明

调用本接口获取任务列表不收费。

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

响应说明

接口返回 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	创建任务时指定的搜索引擎
`se_type`	string	搜索引擎类型
`function`	string	任务类型
`date_posted`	string	任务提交时间，UTC 格式
`endpoint_advanced`	string	获取 Wp V2 高级结果的 URL
`endpoint_html`	string	获取 Wp V2 HTML 结果的 URL。如果对应端点不支持 HTML 任务，则返回 `null`

请求示例

cURL

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/app_data/wp/v2/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(
            "API 错误：代码=%s，消息=%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 错误：", response.status_code, response.text)

TypeScript

typescript

import axios from "axios";

axios
  .get("https://api.seermartech.cn/v3/app_data/wp/v2/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.error("请求失败：", error.response?.data || error.message);
  });

响应示例

json

{
  "version": "0.1.20220422",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1098 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0950 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "app_data",
        "wp",
        "v2",
        "tasks_ready"
      ],
      "data": {
        "se_type": "v2",
        "se": "wp",
        "api": "app_data",
        "function": "v2"
      },
      "result": [
        {
          "id": "11111111-2222-3333-4444-555555555555",
          "se": "wp",
          "se_type": "v2",
          "function": "v2",
          "date_posted": "2024-01-15 10:20:30 +00:00",
          "endpoint_advanced": "/v3/app_data/wp/v2/task_get/11111111-2222-3333-4444-555555555555",
          "endpoint_html": null
        }
      ]
    }
  ]
}

错误处理

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

HTTP 层面的鉴权失败、请求频率限或服务异常。
顶层 status_code 不等于 20000。
tasks_error 大于 0。
单个任务的 status_code 不等于 20000。
endpoint_html 为 null 时，不要继续请求 HTML 结果接口。
任务已保留期限，导致无法在领取列表中查询到。

完整响应码和错误说明请参考 /v3/appendix/errors。

实用场景

轮询已完成任务：定期获取未领取的任务 ID，并批量拉取结果，业务系统遗漏异步任务。
补偿失败回调任务：筛选未成功推送到回调地址的任务，建立结果补偿机制，提升数据采集完整性。
构建任务监控面板：统计领取任务数量、失败数量和任务状态，及时发现采集链路异常。
控制结果消费节奏：每分钟调用限制和单次最多 1000 个任务的规则分批领取结果，降低系统峰值压力。
同步 SEO 数据流水线：将已完成的搜索引擎任务自动转交给、排名或分析流程，缩短数据从采集到分析的周期。

app_data/tasks_ready ​

获取已完成任务列表 ​

请求路径 ​

使用限制 ​

计费说明 ​

响应说明 ​

顶层字段 ​

tasks 对象字段 ​

result 对象字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​

app_data/tasks_ready

获取已完成任务列表

请求路径

使用限制

计费说明

响应说明

顶层字段

`tasks` 对象字段

`result` 对象字段

请求示例

cURL

Python

TypeScript

响应示例

错误处理

实用场景