On-Page 任务就绪列表

接口说明

/v3/on_page/tasks_ready 用于获取已经执行完成、但结果尚未被拉取的 On-Page 任务列表。

调用方式：

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

该接口适合用于轮询已完成任务，再根据返回的任务 id 继续请求对应结果接口（例如 /v3/on_page/summary/{id}）。

计费与调用限制

• 获取该列表不额外收费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 已完成的任务会保留在列表中，直到结果被成功拉取
• 单次调用最多返回过去 3 天完成的 1000 个任务
• 已经拉取过结果的任务不会再出现在列表中
• 完成后** 3 天仍未拉取**的任务，也不会继续保留在列表中
• 调用频率上限：每分钟 20 次

说明：本接口通常返回 cost: 0，即不产生额外费用。

请求信息

请求方法

GET

请求地址

https://api.seermartech.cn/v3/on_page/tasks_ready

请求头

请求头	类型	是否填	说明
Authorization	string	是	认证信息，格式：Bearer smt_live_YOUR_KEY
Content-Type	string	是	固定为 application/json

响应结构

接口返回 JSON 对象，顶层 tasks 数组每个表示一个任务执行结果容器。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码；完整列表参考 /v3/appendix/errors
status_message	string	通用状态信息；完整列表参考 /v3/appendix/errors
time	string	接口执行耗时，单位秒
cost	float	本次请求总费用，通常为 0
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	array / object	请求 URL 中携带的参数
result	array	已完成任务列表

tasks[].result[] 字段

字段名	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
target	string	创建任务时指定的目标网站
date_posted	string	任务提交时间，UTC 格式
tag	string	自定义任务标识

使用流程建议

1. 调用 /v3/on_page/tasks_ready 获取已完成但未拉取的任务；
2. 从 tasks[].result[] 中读取每个任务的 id；
3. 再调用对应结果接口获取明细，例如：

• /v3/on_page/summary/{id}

4. 成功拉取后，该任务通常不会再出现在就绪列表中。

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/tasks_ready"
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)
 # 可继续遍历 result 中的任务 id，再请求接口
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/on_page/tasks_ready",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then(function (response) {
 // 返回结果数据
 console.log(response.data);
 })
 .catch(function (error) {
 console.error(error);
 });

拉取完成任务后继续获取结果示例

下面示例演示：获取已完成任务列表，再根据任务 id 请求 /v3/on_page/summary/{id}。

Python

import requests

headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

# 第一步：获取已完成任务列表
ready_url = "https://api.seermartech.cn/v3/on_page/tasks_ready"
ready_resp = requests.get(ready_url, headers=headers).json

results = []

if ready_resp.get("status_code") == 20000:
 for task in ready_resp.get("tasks", []):
 for item in task.get("result", []):
 task_id = item.get("id")
 if task_id:
 # 第二步：根据任务 id 获取对应结果
 summary_url = f"https://api.seermartech.cn/v3/on_page/summary/{task_id}"
 summary_resp = requests.get(summary_url, headers=headers).json
 results.append(summary_resp)

print(results)

响应示例

{
 "version": "0.1.20200805",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2772 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "a6f0d9d2-7d7c-4d31-9d8d-1234567890ab",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "on_page",
 "tasks_ready"
 ],
 "data": {
 "api": "on_page",
 "function": "tasks_ready"
 },
 "result": [
 {
 "id": "3f3a6b0d-2b6f-4f78-8e4b-abcdef123456",
 "target": "example.com",
 "date_posted": "2024-01-15 10:20:30 +00:00",
 "tag": "weekly-crawl-project-a"
 }
 ]
 }
 ]
}

常见状态码

状态码	含义
20000	请求成功
10000-60000	任务级状态码范围，表示处理状态或错误信息
错误码	参考 /v3/appendix/errors

注意事项

• 该接口只返回已完成但尚未拉取的任务
• 不会返回已经获取过结果的任务
• 不会返回完成时间 3 天但未拉取的任务
• 建议结合定时轮询机制使用，遗漏结果
• 若任务量较大，建议按固定频率轮询，并及时消费返回的任务 ID

实用场景

• 轮询已完成抓取任务：自动发现哪些站点页面分析任务已执行完毕，减少无效查询与时间。
• 批量拉取页面审计结果：获取就绪任务，再按 id 批量请求摘要或，提升技术 SEO 数据回收效率。
• 监控多项目爬取队列：结合 tag 区分不同客户或项目，快速判断各项目最近完成了哪些页面分析任务。
• 构建异步任务消费系统：将本接口作为任务完成通知，驱动数据处理、告警或报表生成流程。
• 排查结果遗漏问题：通过检查最近 3 天未拉取的已完成任务，及时补采分析结果， SEO 审计数据缺失。