获取已修复的 SERP 任务列表

接口说明

Tasks Fixed 接口用于获取已完成重新解析（re-parsed markup）但尚未被拉取的 SERP 任务列表。

如果您使用 Standard 方式创建任务，且未设置 postback_url，则可以通过本接口获取所有已完成修复任务的 id。拿到任务 id 后，再调用对应的 Task GET 接口重新拉取修复后的结果。

该接口适用于 SERP 标记修复后的结果补采集场景。

请求地址

GET https://api.seermartech.cn/v3/serp/$path/tasks_fixed

，$path 为动态路径参数，表示搜索引擎与结果类型。

计费说明

获取该列表不会产生费用。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

动态路径参数

path：端点路径，需在 GET URL 中指定搜索引擎及类型。

可选值如下：

• google/organic
• google/maps
• google/news
• google/events
• google/images
• google/search_by_image
• google/jobs
• google/local_finder
• google/dataset_search
• google/dataset_info
• google/autocomplete
• google/ai_mode
• bing/organic
• yahoo/organic
• baidu/organic
• naver/organic
• seznam/organic
• youtube/organic
• youtube/video_info
• youtube/video_subtitles
• youtube/video_comments

使用规则

• 每个已修复任务会一直保留在列表中，直到被成功拉取。
• 每分钟最多可调用 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
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 结果的 URL；若当前端点不支持，则为 null
endpoint_advanced	string	获取 SERP Advanced 结果的 URL；若当前端点不支持，则为 null
endpoint_html	string	获取 SERP HTML 结果的 URL；若当前端点不支持，则为 null

调用示例

cURL

# 可将 google/organic 替换为任意支持的 SERP 引擎与类型
curl --location --request GET "https://api.seermartech.cn/v3/serp/google/organic/tasks_fixed" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

url = "https://api.seermartech.cn/v3/serp/google/organic/tasks_fixed"
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)
 # 在此处理任务列表，并继续调用对应 Task GET 接口
else:
 print(f"error. Code: {result.get('status_code')} Message: {result.get('status_message')}")

TypeScript

import axios from "axios";

// 可将 google/organic 替换为任意支持的 SERP 引擎与类型
axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/serp/google/organic/tasks_fixed",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then(function (response) {
 const result = response.data;
 // 返回结果
 console.log(result);
 })
 .catch(function (error) {
 console.log(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": "google",
 "se_type": "organic"
 },
 "result": []
 }
 ]
}

结果拉取建议

获取到 tasks_fixed 返回的任务 id 后，建议立即调用对应的 Task GET 接口重新采集修复后的结果， 24 小时保留窗口后无法再次通过本接口获取。

常见流程如下：

1. 提交 SERP 任务；
2. 未设置 postback_url 时，轮询 /v3/serp/{engine}/{type}/tasks_fixed；
3. 获取已修复任务 id；
4. 调用对应 Task GET 接口拉取修复后的结果；
5. 持化结果并标记为已处理。

错误处理

请重点以下字段：

• 顶层 status_code：判断本次接口调用是否成功；
• 顶层 tasks_error：判断返回任务中是否存在错误；
• tasks[].status_code：判断单个任务状态；
• tasks[].status_message：查看错误或提示信息。

完整错误码与状态说明参考：

• /v3/appendix/errors

实用场景

• 补拉修复后的 SERP 结果：在未回调通知时，定时查询已修复任务列表，遗漏重新解析后的可用数据。
• 底失败回调任务：当业务系统接收 postback_url 失败时，通过本接口重新发现任务并补采，提升结果交付稳定性。
• 追踪解析质量修复：识别哪些历史 SERP 任务被平台重新修复，便于重新库并提升排名、URL、摘要等字段的准确性。
• 驱动自动二次采集流程：将 tasks_fixed 接口接任务队列，自动触发对应 Task GET 拉取，构建无人值守的数据修复流水线。
• 校验近 24 小时漏采任务：按时间窗口巡检最近已完成但未落库的修复任务，降低因任务遗漏导致的 SEO 分析偏差。