获取 LLM Scraper 已完成任务列表

接口说明

Tasks Ready 接口用于返回已执行完成但尚未被获取结果的任务列表。

如果你使用标准提交方式，且未设置 postback_url，可以通过本接口获取所有已完成任务的 id，随后再调用对应的 Task GET 接口拉取任务结果。

如果你的系统需要了解任务完成状态并批量获取可拉取任务，本接口适合作为轮询。

注意： 由于平台 API 的任务队列存在短暂刷新延迟，高并发场景下可能无法做到实时无延迟返回。 如果你的系统需要每分钟处理 1000 个任务，建议优使用回调机制（pingback/postback），而将本接口用于补偿获取回调失败任务的 ID。

请求信息

请求方式： GET请求地址：

/v3/ai_optimization/wp/v2/tasks_ready

完整示例：

https://api.seermartech.cn/v3/ai_optimization/wp/v2/tasks_ready

计费与限制

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

postback_url 的行为

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

只有在以下时，该任务才可能重新出现在本接口返回结果中：

• 向你的服务器发送回调失败
• 你的服务器返回的 HTTP 状态码小于 200或大于 300

响应结构

接口返回 JSON 数据，顶层 tasks 数组存放本次返回的任务信息。

顶层字段

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

result 数组中的字段

字段名	类型	说明
id	string	已完成任务的唯一标识，UUID 格式
se	string	创建任务时指定的搜索引擎
se_type	string	搜索引擎类型，例如 v2
date_posted	string	任务提交时间，UTC 格式
tag	string	用户自定义任务标记
endpoint_regular	string	拉取 Regular 结果的 URL；如果该端点不支持 Regular，则为 null
endpoint_advanced	string	拉取 Advanced 结果的 URL；如果该端点不支持 Advanced，则为 null
endpoint_html	string	拉取 HTML 结果的 URL；如果该端点不支持 HTML，则为 null

调用示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/wp/v2/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)
 # 在此处理已完成任务列表
else:
 print(f"error. Code: {data.get('status_code')} Message: {data.get('status_message')}")

TypeScript

import axios from "axios";

async function getTasksReady {
 try {
 const response = await axios.get(
 "https://api.seermartech.cn/v3/ai_optimization/wp/v2/tasks_ready",
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 const result = response.data;

 if (result.status_code === 20000) {
 console.log(result);
 // 在此处理已完成任务列表
 } else {
 console.log(`error. Code: ${result.status_code} Message: ${result.status_message}`);
 }
 } catch (error) {
 console.error(error);
 }
}

getTasksReady;

响应示例

{
 "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": "ai_optimization",
 "function": "tasks_ready",
 "se": "wp",
 "se_type": "v2"
 },
 "result": []
 }
 ]
}

使用建议

1. 轮询频率控制 建议遵守每分钟 20 次的调用限制，无效高频轮询。

2. 结果拉取闭环 获取到 result[].id 后，立即调用对应的 Task GET 端点获取结果，任务在 3 天后失效。

3. 优使用回调机制处理大规模任务 如果任务量较大，建议采用 postback/pingback 作为主流程，本接口作为补偿机制使用。

4. 可用结果端点 并非所有任务类型都支持 regular、advanced、html 三类结果。拉取前请检查 endpoint_regular、endpoint_advanced、endpoint_html 是否为 null。

常见状态说明

状态码	含义
20000	请求成功
状态码	表示接口级或任务级异常，详见 /v3/appendix/errors

实用场景

• 轮询已完成采集任务：批量获取已完成但未拉取的任务 ID，构建稳定的结果拉取队列，减少漏单风险。
• 补偿回调失败任务：当业务系统未成功接收 postback 时，通过本接口找回任务并重新获取结果，提升数据完整性。
• 监控任务处理吞吐：按时间窗口统计完成任务数量，用于评估采集链路处理效率和队列积压。
• 驱动异步结果库：通过本接口获取可用任务，再调用结果接口写数据库，适合搭建异步 SEO 数据处理流水线。
• 审计任务生命周期：结合 date_posted、tag 和结果端点信息，追踪任务从提交到结果消费的，便于排查异常。