On-Page 任务就绪列表

GET /v3/on_page/tasks_ready

本接口使用 GET /v3/on_page/tasks_ready，用于获取已完成但尚未拉取结果的 On-Page 任务列表。

接口说明

• 请求方法：GET
• 请求路径：/v3/on_page/tasks_ready
• 完整 URL：https://api.seermartech.cn/v3/on_page/tasks_ready
• 请求体：无
• 返回格式：JSON

每个任务在成功获取结果前都会保留在列表中。接口每分钟最多调用 20 次，每次最多返回过去 3 天完成的 1000 个任务。

以下任务不会出现在列表中：

• 已经获取过结果的任务；
• 完成后 3 天仍未获取结果的任务。

获取到任务 ID 后，可继续调用对应的结果接口，例如：

GET /v3/on_page/summary/{id}

计费说明

获取任务就绪列表及接收结果不收取费用，接口返回的 cost 通常为 0。

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

请求示例

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"

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((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || error.message);
  });

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)

if response.status_code == 200:
    result = response.json()
    if result.get("status_code") == 20000:
        print(result)
    else:
        print(
            "业务错误。错误码：%s，错误信息：%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 错误：%s，响应：%s" % (response.status_code, response.text))

PHP

<?php

$url = 'https://api.seermartech.cn/v3/on_page/tasks_ready';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new Exception(curl_error($ch));
}

curl_close($ch);

$result = json_decode($response, true);

if (($result['status_code'] ?? null) === 20000) {
    print_r($result);
} else {
    echo '错误码：' . ($result['status_code'] ?? '未知');
    echo '，错误信息：' . ($result['status_message'] ?? '未知') . PHP_EOL;
}

响应结构

接口返回 JSON 对象 tasks 数组已完成但尚未获取结果的任务。

{
  "version": "0.1.20200805",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2772 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "072844 ಮಾಡುವ-0001-0000-0000-000000000001",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1532 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "tasks_ready"
      ],
      "data": {
        "api": "on_page",
        "function": "tasks_ready"
      },
      "result": [
        {
          "id": "072844ab-0001-0000-0000-000000000001",
          "target": "https://example.com",
          "date_posted": "2024-01-01 12:00:00 +00:00",
          "tag": "site-audit-001"
        }
      ]
    }
  ]
}

> id 用于标识任务。返回数据以接口响应为准。

响应字段

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	接口整体状态码。20000 表示成功
status_message	string	接口整体状态信息
time	string	接口执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
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 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的结果数量
path	array	请求 URL 的路径组成部分
data	object	创建任务时传的请求参数
result	array	已完成任务的摘要信息

result 子项字段

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

获取任务结果

从 result[].id 中获取任务 ID 后，可调用相应的结果接口。例如，On-Page 概要结果可通过以下接口获取：

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

将 {id} 替换为任务 ID。成功获取结果后，该任务将不再出现在 tasks_ready 列表中。

状态码

状态码	说明
20000	请求成功
状态码	请求或任务处理失败，含义以响应中的 status_message 为准

实用场景

• 轮询已完成任务：定时获取已完成的 On-Page 审计任务，及时触发结果拉取，缩短 SEO 报告生成时间。
• 批量收集站点审计结果：一次获取多个已完成任务，集中处理大量网站的技术 SEO 检查数据。
• 构建异步任务队列：根据任务 ID 和状态码管理任务生命周期，重复请求或遗漏结果。
• 业务项目与任务：利用 tag 区分客户、站点或项目，便于将审计结果写对应业务记录。
• 监控任务处理状态：结合 tasks_count、tasks_error 和任务级状态码，监测批量爬取任务是否存在异常。