获取浩搜自然搜索结果的已完成任务

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

/v3/serp/haosou/organic/tasks_ready

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

接口信息

• 请求方法： GET
• 请求地址： https://api.seermartech.cn/v3/serp/haosou/organic/tasks_ready
• 计费： 获取已完成任务列表不计费
• 请求频率： 每分钟最多调用 20 次
• 单次返回： 最多返回过去 3 天完成的 1000 个任务

每个任务会一直保留在列表中，直到被成功取回。任务完成 3 天仍未取回后，将不会继续出现在列表中。

如果提交任务时设置了 postback_url，任务通常不会出现在本接口返回列表中。只有当平台向您的服务器推送失败，且服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在已完成任务列表中。

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

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/serp/haosou/organic/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(
        "请求失败。错误码：{}，消息：{}".format(
            result.get("status_code"),
            result.get("status_message"),
        )
    )

TypeScript

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/serp/haosou/organic/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);
  });

响应结构

接口返回 JSON 数据 tasks 数组已完成任务的信息。

顶层字段

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

tasks.result 字段

字段	类型	说明
id	string	已完成任务的唯一标识，UUID 格式
se	string	创建任务时指定的搜索引擎
se_type	string	搜索引擎类型。当前为 organic
date_posted	string	任务提交时间，采用 UTC 格式
tag	string	用户自定义任务标识
endpoint_regular	string / null	获取 SERP Regular 结果的接口地址。如果当前端点不支持 SERP Regular，则为 null
endpoint_advanced	string / null	获取 SERP Advanced 结果的接口地址。如果当前端点不支持 SERP Advanced，则为 null
endpoint_html	string / null	获取 SERP HTML 结果的接口地址。如果当前端点不支持 SERP HTML，则为 null

响应示例

{
  "version": "0.1.20200129",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2270 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1980 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "haosou",
        "organic",
        "tasks_ready"
      ],
      "data": {
        "api": "serp",
        "function": "tasks_ready",
        "se": "haosou",
        "se_type": "organic"
      },
      "result": [
        {
          "id": "01234567-89ab-cdef-0123-456789abcdef",
          "se": "haosou",
          "se_type": "organic",
          "date_posted": "2024-01-29 12:00:00 +00:00",
          "tag": "example-task",
          "endpoint_regular": "/v3/serp/haosou/organic/task_get/01234567-89ab-cdef-0123-456789abcdef",
          "endpoint_advanced": null,
          "endpoint_html": null
        }
      ]
    }
  ]
}

使用说明

1. 调用任务创建接口提交自然搜索结果查询任务。
2. 未设置 postback_url 时，定期调用本接口轮询已完成任务。
3. 从 tasks.result 中读取任务 id 或结果接口地址。
4. 调用对应的任务获取接口读取 SERP 结果。
5. 成功取回后，任务将从已完成任务列表中移除。

建议在业务系统中对请求级和任务级状态码分别进行处理，并为时、任务过期、结果获取失败等异常设计重试和告警机制。

实用场景

• 轮询已完成任务：批量发现已经完成的浩搜自然搜索任务，减少逐个查询任务状态的请求开销。
• 收集 SERP 结果：获取任务 ID 后继续调用结果接口，构建排名、竞争对手和搜索结果页面数据集。
• 管理异步采集流程：在未回调地址的场景下，通过定时任务稳定获取异步任务结果。
• 监控任务积压：统计 tasks_count 和 tasks_error，及时发现采集延迟或错误率升高的问题。
• 补偿失败任务：识别未及时取回或结果获取失败的任务，并结合任务状态码执行重试或异常处理。