获取 Gemini LLM Scraper 已完成任务列表

接口说明

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

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

如需了解任务完成机制以及已完成任务列表的获取方式，可参考帮助文档。

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

请求信息

请求方式： GET请求地址：

https://api.seermartech.cn/v3/ai_optimization/gemini/llm_scraper/tasks_ready

计费与调用限制

• 拉取已完成任务列表不额外收费
• 每个已完成任务会一直保留在列表中，直到你成功拉取
• 每分钟最多可调用 20 次
• 每次调用最多可返回最近 3 天完成的 1000 个任务
• 以下任务不会出现在列表中：
• 已经被成功获取结果的任务
• 任务完成后 3 天未拉取 的任务
• 已设置 postback_url 且回调成功的任务

如果设置了 postback_url，任务通常不会出现在已完成任务列表中。当回调到你的服务端失败时，该任务才可能列表，例如：

• 你的服务端未成功接收请求
• 返回的 HTTP 状态码 小于 200 或 大于 300

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

响应结构

接口返回 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	当前请求任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表见 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	该任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	URL 中传的路径参数
result	array	已完成任务结果列表

tasks[].result[] 字段

字段	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎/数据源
function	string	功能类型，例如 llm_scraper
date_posted	string	任务提交时间，UTC 格式
tag	string	你自定义的任务标识
endpoint_advanced	string	用于获取 Advanced 结果的接口地址；若该端点不支持 Advanced，则为 null
endpoint_html	string	用于获取 HTML 结果的接口地址；若该端点不支持 HTML，则为 null

调用示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/ai_optimization/gemini/llm_scraper/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/gemini/llm_scraper/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)
 # 后续可遍历 result["tasks"] 或的 result 列表，提取已完成任务 ID
else:
 print(f'error. Code: {result.get("status_code")} Message: {result.get("status_message")}')

TypeScript

import axios from "axios";

axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/ai_optimization/gemini/llm_scraper/tasks_ready",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 const result = response.data;
 // 返回结果数据
 console.log(result);
 })
 .catch((error) => {
 console.log(error);
 });

响应示例

{
 "version": "0.1.20260218",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1259 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "ai_optimization",
 "function": "llm_scraper",
 "se": "gemini"
 },
 "result": []
 }
 ]
}

使用建议

1. 拉列表，再取 本接口返回已完成任务的标识及结果信息，结果通常需要通过对应的 Task GET 接口获取。

2. 高频场景优使用回调 如果你的任务量很大，不建议依赖轮询 tasks_ready；应优 postback_url，用回调接收结果。

3. 将本接口用于失败补偿 已回调时，可把本接口作为回补机制，专门查找那些因回调失败而未成功库的任务。

4. 注意 3 天有效期 已完成任务在完成后的 3 天窗口可通过该列表发现，建议尽快消费并归档。

错误处理

请重点以下几类：

• 顶层 status_code 不为 20000
• tasks_error 大于 0
• tasks 数组为空
• result 数组为空，表示当前没有可拉取的已完成任务
• 已创建 postback_url 但任务未出现在列表中，这通常表示回调已成功完成

完整错误码与状态说明请参考：/v3/appendix/errors

实用场景

• 轮询取结果：在未回调时，定时获取最近完成的任务 ID，驱动后续结果抓取流程，漏取任务。
• 补偿失败回调：对接 postback_url 后，定期检查回调失败任务并重新获取结果，提升任务库完整率。
• 监控任务吞吐：统计最近 3 天完成任务数量与完成节奏，用于评估批量采集效率和系统处理能力。
• 业务标签：结合返回的 tag 字段，将已完成任务映射到项目、客户或分析批次，方便自动化归档。
• 分发结果拉取任务：获取已完成任务列表，再按 endpoint_advanced 或结果分给不同处理，提高结果消费效率。