SeerMarTech API 文档

主题

按任务 ID 获取 Lighthouse 审计结果 ​

GET /v3/appendix/errors

本接口使用 GET 方法，通过任务 ID 获取 Lighthouse 审计结果：

GET https://api.seermartech.cn/v3/on_page/lighthouse/task_get/json/$id

本接口基于开源 Lighthouse 项目，用于获取网页或 Web 应用的性能、可访问性、渐进式 Web 应用、SEO 及最佳实践等审计数据。任务 ID 来自提交 Lighthouse 任务的 POST 接口响应。响应中的 result取决于创建任务时指定的分类和审计项；未指定时，通常返回网页可用的完整审计数据。

> 如果审计项名称斜杠 /，请使用斜杠后的最后一个单词在 audits 对象中查找对应结果。

请求 ​

请求参数 ​

参数类型填说明
idstring是任务唯一标识符。可从 Lighthouse Task POST 接口的响应中获取，格式为 UUID。示例：07131248-1535-0216-1000-17384017ad04

请求示例 ​

bash
id="07281559-0695-0216-0000-c269be8b7592"

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

本接口为 GET 请求，不需要请求体。

Python ​

python
from client import RestClient

client = RestClient("smt_live_YOUR_KEY")

# 根据任务 ID 获取 Lighthouse 结果
task_id = "07281559-0695-0216-0000-c269be8b7592"
response = client.get(
    "/v3/on_page/lighthouse/task_get/json/" + task_id
)

if response.get("status_code") == 20000:
    print(response)
else:
    print(
        "请求失败，状态码：%s，消息：%s"
        % (response.get("status_code"), response.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

const taskId = "07281559-0695-0216-0000-c269be8b7592";

axios.get(
  `https://api.seermartech.cn/v3/on_page/lighthouse/task_get/json/${taskId}`,
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
)
.then((response) => {
  // Lighthouse 结果
  console.log(response.data);
})
.catch((error) => {
  console.error("请求失败：", error.response?.data || error.message);
});

计费说明 ​

本接口用于读取已提交任务的结果，通常不会产生额外的任务费用。费用在提交任务时产生，扣费以任务提交接口的响应为准。

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

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger请求总体状态码。完整状态码列表请参考 /v3/appendix/errors
status_messagestring请求总体说明信息
timestring请求执行耗时，单位为秒
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务结果数组

tasks 数组中的字段 ​

字段类型说明
idstring任务唯一标识符，UUID 格式
status_codeinteger任务状态码，通常为 10000 至 60000
status_messagestring任务状态说明
timestring任务执行耗时，单位为秒
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量
patharray请求 URL 的路径信息
dataobject创建任务时提交的参数
resultarrayLighthouse 审计结果数组

data 字段 ​

data含创建任务时使用的主要参数，例如：

字段类型说明
apistringAPI 模块，例如 on_page
functionstring功能名称，例如 lighthouse
urlstring执行审计的网页 URL
for_mobileboolean是否使用移动设备执行审计
categoriesarray创建任务时指定的 Lighthouse 分类

result 字段 ​

result 是 Lighthouse 的详细审计结果，字段会随任务参数和 Lighthouse 版本变化。常见字段：

字段类型说明
userAgentstring执行审计时使用的用户代理
environmentobject执行环境及基准信息
auditsobject各项审计结果，键名为审计 ID
categoriesobject分类级评分，例如性能评分
categoryGroupsobject审计分组及说明
configSettingsobjectLighthouse置设备、网络、CPU 和屏幕模拟设置
timingobjectLighthouse 执行时序信息
i18nobjectLighthouse化文本及格式化信息
fullPageScreenshotobject页截图信息；可能 Base64 编码图片
entitiesarray页面中识别出的第三方实体及资源信息

audits 中的常见审计字段 ​

每个审计项通常以下字段：

字段类型说明
idstring审计项 ID，例如 largest-contentful-paint
titlestring审计项标题
descriptionstring审计项说明
scorefloat/null审计得分，范围通常为 0 至 1；不适用时为 null
scoreDisplayModestring得分展示模式，例如 numeric、informative、metricSavings
numericValuenumber数值型审计结果
numericUnitstring数值单位，例如 millisecond、byte
displayValuestring面向用户展示的格式化结果
scoringOptionsobject评分阈值或参考值
metricSavingsobject预计可改善的指标或节省量
detailsobject表格、节点、机会项、截图或调试数据
warningsarray审计警告
guidanceLevelinteger建议处理优级

响应示例 ​

以下示例展示主要结构。响应中的 audits、截图、网络请求和节点信息可能大量数据。

json
{
  "version": "0.1.20260318",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0919 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0919 sec.",
      "cost": 0,
      "result_count": 1,
      "data": {
        "api": "on_page",
        "function": "lighthouse",
        "url": "https://www.example.com",
        "for_mobile": false,
        "categories": ["performance"]
      },
      "result": [
        {
          "audits": {
            "first-contentful-paint": {
              "id": "first-contentful-paint",
              "title": "First Contentful Paint",
              "score": 0.98,
              "scoreDisplayMode": "numeric",
              "numericValue": 694.264,
              "numericUnit": "millisecond",
              "displayValue": "0.7 s"
            },
            "largest-contentful-paint": {
              "id": "largest-contentful-paint",
              "title": "Largest Contentful Paint",
              "score": 0.87,
              "scoreDisplayMode": "numeric",
              "numericValue": 1284.36,
              "numericUnit": "millisecond",
              "displayValue": "1.3 s"
            },
            "cumulative-layout-shift": {
              "id": "cumulative-layout-shift",
              "title": "Cumulative Layout Shift",
              "score": 1,
              "scoreDisplayMode": "numeric",
              "numericValue": 0.00936,
              "numericUnit": "unitless",
              "displayValue": "0.009"
            }
          },
          "categories": {
            "performance": {
              "id": "performance",
              "title": "Performance",
              "score": 0.93
            }
          },
          "configSettings": {
            "formFactor": "desktop",
            "locale": "en-US",
            "screenEmulation": {
              "mobile": false,
              "width": 1350,
              "height": 940,
              "deviceScaleFactor": 1
            },
            "throttlingMethod": "simulate"
          }
        }
      ]
    }
  ]
}

状态码与异常处理 ​

建议同时检查以下状态码：

  1. HTTP 状态码，用于判断网络层和服务层请求是否成功。
  2. 顶层 status_code，用于判断本次 API 请求是否成功。
  3. tasks[].status_code，用于判断任务是否成功。
  4. tasks[].result 是否存在，用于判断任务是否返回有效结果。

当任务状态码表示失败，或 result 为空时，应读取对应的 status_message，并业务需要进行重试、记录或告警。完整错误码列表请参考 /v3/appendix/errors。

注意事项 ​

-须使用创建任务时返回的任务 ID 请求结果。

  • 任务尚未完成时，可能暂时无法获取完整的 result 数据。
  • Lighthouse 结果会受到设备模拟、网络条件、CPU置及页面动态影响。
  • score 为 null 时，通常表示该审计不适用，或不参与对应分类评分。
  • fullPageScreenshot.screenshot.data 和截图类审计可能返回较大的 Base64 字符串，建议按需存储或删除。
  • 如果只需要少量指标，建议在创建任务时限制 categories 或审计项，减少响应体积和处理成本。
  • audits 的完整字段定义以当前 Lighthouse 版本为准。

实用场景 ​

  • 监控核心网页指标：定期获取 FCP、LCP、CLS、TBT 等 Lighthouse 指标，及时发现页面性能回退并降低自然流量损失。
  • 定位页面加载瓶颈：分析网络请求、主线程任务、渲染阻塞资源和服务器响应时间，为前端及后端优化提供明确依据。
  • 执行移动端 SEO 检查：获取移动设备模拟下的可用性、视口、及抓取审计结果，提升移动搜索体验。
  • 生成技术 SEO 报告：汇总性能、可访问性、SEO 和最佳实践分类评分，为客户交付、月报和整改验收提供数据。
  • 对比优化前后效果：保存不同版本的 Lighthouse 结果，比较评分、资源体积和预计节省量，量化技术优化带来的收益。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API