获取已修复的 WP V2 SERP 任务列表

接口说明

Tasks Fixed 接口用于获取“已重新解析但尚未被拉取”的任务列表。

如果您使用标准提交方式，且未设置 postback_url，可通过本接口获取所有已完成修复任务的 id。拿到这些 id 后，再通过对应的 Task GET 接口重新拉取修复后的结果。

该接口适用于 SERP 标记被平台重新解析后，批量发现有哪些任务产生了“修复版结果”的场景。

请求地址

GET /v3/serp/wp/v2/tasks_fixed

完整请求 URL：

https://api.seermartech.cn/v3/serp/wp/v2/tasks_fixed

计费与调用限制

• 获取该列表不会产生额外费用
• 每分钟最多可调用 20 次
• 每次调用最多返回 最近 24 小时完成的 1000 个任务
• 某个任务会一直保留在列表中，直到您成功拉取修复结果
• 以下任务不会出现在列表中：
• 已经被成功拉取的任务
• 在任务完成后 24 小时未拉取 的任务

postback_url 的说明

如果创建任务时设置了 postback_url，该任务通常不会出现在已完成任务列表中。

当回调请求发送到您的服务器失败，且您的服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能出现在此列表中，供您后续主动补拉。

返回结果说明

接口返回 JSON 数据，顶层 tasks 数组，用于描述本次查询返回的任务信息。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	接口级状态码，完整列表参考 /v3/appendix/errors
status_message	string	接口级状态信息，完整列表参考 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD；本接口通常为 0，扣费以响应头 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
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	请求 URL 中传的参数
result	array	结果数组

tasks[].result[] 字段

字段	类型	说明
id	string	已完成修复任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎
se_type	string	搜索引擎类型；该接口中为 v2
date_fixed	string	任务被修复的时间，UTC 格式
tag	string	用户自定义任务标识
endpoint_regular	string	拉取 SERP Regular 结果的接口地址；如该端点不支持，则为 null
endpoint_advanced	string	拉取 SERP Advanced 结果的接口地址；如该端点不支持，则为 null
endpoint_html	string	拉取 SERP HTML 结果的接口地址；如该端点不支持，则为 null

使用建议

建议您为以下设计补偿机制与异常处理逻辑：

• 定时轮询 /v3/serp/wp/v2/tasks_fixed
• 发现有修复任务后，按 result[].id 调用对应的 Task GET 接口重新获取结果
• 记录已处理任务，重复消费
• 对 /v3/appendix/errors 中的状态码进行统一处理
• 对 24 小时仍未拉取的任务设置底告警

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/tasks_fixed"
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(f"error. Code: {data.get('status_code')} Message: {data.get('status_message')}")

TypeScript

import axios from "axios";

axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/serp/wp/v2/tasks_fixed",
 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);
});

响应示例

{
 "version": "0.1.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2270 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "tasks_fixed",
 "se": "wp",
 "se_type": "v2"
 },
 "result": []
 }
 ]
}

状态码与错误处理

• 20000：请求成功
• 状态码：表示接口级或任务级错误

建议同时检查以下两个层级：

1. 顶层 status_code / status_message
2. tasks[]每个任务的 status_code / status_message

完整错误码定义可参考：

/v3/appendix/errors

型处理流程

1. 调用 /v3/serp/wp/v2/tasks_fixed
2. 遍历 tasks[].result[]
3. 获取每个修复任务的 id
4. 根据 endpoint_regular、endpoint_advanced 或 endpoint_html 选择对应结果接口
5. 调用相应 Task GET 接口重新获取修复后的 SERP 数据

实用场景

• 补拉修复后的 SERP 结果：发现平台已重新解析的任务后重新取回结果，减少因原始标记异常导致的数据缺失。
• 监控回调失败任务：对设置了 postback_url 但回调失败的任务进行补偿拉取，提升数据交付稳定性。
• 修正排名数据库：将修复后的结果重新写排名库，降低历史 SERP 记录中的解析误差。
• 重建富结果字段：针对依赖 Advanced 或 HTML 结果的业务，重新获取结构化页面，完善精选摘要、站点链接等字段。
• 建立 24 小时补采机制：在任务完成后的有效窗口自动扫描并补采，修复结果因时未取而丢失。