OnPage 瀑布流性能分析

POST /v3/on_page/waterfall

本接口使用 POST 方法，路径为：

/v3/on_page/waterfall

用于获取指定页面的加载瀑布流数据和页面速度指标页面加载时间、建立连接耗时、资源加载耗时等。适合构建页面测速、性能监控和网站技术审计。

计费说明

本功能不收取任务创建费用。任务结果可在任务完成后的 30 天获取。

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

请求说明

请求体使用 UTF-8 编码的 JSON 数组：

json

[
  {
    "id": "07131248-1535-0216-1000-17384017ad04",
    "url": "https://www.example.com/"
  }
]

，id 为通过 /v3/on_page/task_post/ 创建任务时获得的任务 ID。

请求参数

参数	类型	说明
`id`	string	填。任务 ID。可从 `/v3/on_page/task_post/` 接口的响应中获取。示例：`07131248-1535-0216-1000-17384017ad04`
`url`	string	填。需要获取加载时序数据的页面 URL。
`tag`	string	可选。自定义任务标识，最长 255 个字符。可用于识别任务并与结果进行匹。提交的值会原样返回在响应的 `data` 对象中。

响应结构

接口返回 JSON 数据，主要顶层任务状态和 tasks 任务数组。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用响应状态码。完整错误码请参考错误码文档。建议客户端实现错误和异常处理机制。
`status_message`	string	通用状态说明。
`time`	string	接口执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`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` 字段

字段	类型	说明
`crawl_progress`	string	抓取会话状态。可选值：`in_progress`、`finished`。
`crawl_status`	object	抓取会话详细状态。
`items`	array	页面性能及资源时序数据数组。

`crawl_status` 字段

字段	类型	说明
`max_crawl_pages`	integer	最大抓取页面数，对应创建任务时设置的 `max_crawl_pages` 限制。
`pages_in_queue`	integer	当前仍在抓取队列中的页面数。
`pages_crawled`	integer	已抓取页面数。
`items_count`	integer	结果数组中的数据项数量。

`items` 页面性能字段

字段	类型	说明
`page_url`	string	页面 URL。
`time_to_interactive`	integer	可交互时间（TTI），即用户可以与页面进行交互所需的时间，单位为毫秒。
`dom_complete`	integer	DOM 完成时间，即页面及所有子资源下载完成所需的时间，单位为毫秒。
`connection_time`	integer	建立服务器连接所需的时间，单位为毫秒。
`time_to_secure_connection`	integer	建立连接所需的时间，单位为毫秒。
`request_sent_time`	integer	向服务器发送请求所需的时间，单位为毫秒。
`waiting_time`	integer	首字节时间（TTFB），单位为毫秒。
`download_time`	integer	浏览器接收响应所需的时间，单位为毫秒。
`duration_time`	integer	浏览器接收服务器完整响应所需的总时间，单位为毫秒。
`fetch_start`	integer	开始下载 HTML 资源的时间。
`fetch_end`	integer	完成下载 HTML 资源的时间。
`resources`	array	页面中各资源的独立加载时序数据。

`resources` 资源字段

字段	类型	说明
`resource_type`	string	资源类型。
`url`	string	资源 URL。
`initiator`	string	资源发起方。
`duration_time`	integer	浏览器接收该资源完整响应所需的总时间，单位为毫秒。
`fetch_start`	integer	开始下载该资源的时间。
`fetch_end`	integer	完成下载该资源的时间。
`location`	object	资源在 HTML 文档中的位置。
`is_render_blocking`	boolean	是否阻塞页面渲染。

`location` 字段

字段	类型	说明
`line`	integer	资源所在的 HTML 行号。
`offset_left`	integer	资源在当前行中的位置，即资源左侧的字符数，也可理解为列号。该值从 `1` 开始计算；如果资源左侧没有字符，则值为 `1`。
`offset_top`	integer	资源与 HTML 文档顶部之间的字符总数。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/on_page/waterfall" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "url": "https://www.example.com/performance-test",
      "tag": "homepage-waterfall"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/on_page/waterfall"

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

payload = [
    {
        "id": "07281559-0695-0216-0000-c269be8b7592",
        "url": "https://www.example.com/performance-test",
        "tag": "homepage-waterfall",
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    id: "07281559-0695-0216-0000-c269be8b7592",
    url: "https://www.example.com/performance-test",
    tag: "homepage-waterfall",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/on_page/waterfall",
    payload,
    {
      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);
  });

响应示例

json

{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1119 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1000 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "waterfall"
      ],
      "data": {
        "api": "on_page",
        "function": "waterfall",
        "url": "https://www.example.com/help-center",
        "target": "www.example.com",
        "max_crawl_pages": 100,
        "load_resources": true
      },
      "result": [
        {
          "crawl_progress": "finished",
          "crawl_status": {
            "max_crawl_pages": 100,
            "pages_in_queue": 0,
            "pages_crawled": 1,
            "items_count": 1
          },
          "items": [
            {
              "page_url": "https://www.example.com/help-center",
              "time_to_interactive": 1250,
              "dom_complete": 980,
              "connection_time": 45,
              "time_to_secure_connection": 62,
              "request_sent_time": 70,
              "waiting_time": 180,
              "download_time": 120,
              "duration_time": 300,
              "fetch_start": 0,
              "fetch_end": 980,
              "resources": [
                {
                  "resource_type": "script",
                  "url": "https://www.example.com/assets/app.js",
                  "initiator": "https://www.example.com/help-center",
                  "duration_time": 210,
                  "fetch_start": 100,
                  "fetch_end": 310,
                  "location": {
                    "line": 18,
                    "offset_left": 1,
                    "offset_top": 482
                  },
                  "is_render_blocking": true
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

> 上述数值用于展示响应结构，结果取决于目标页面、网络环境和页面资源。

实用场景

定位页面加载瓶颈：拆分连接、首字节、下载和 DOM 完成等耗时，帮助技术团队确定影响 SEO 和用户体验的环节。
识别渲染阻塞资源：筛选 is_render_blocking 为 true 的 CSS、JavaScript 等资源，指导前端优化首屏渲染速度。
构建批量页面测速：对首页、落地页和核心转化页面批量采集 TTI、TTFB 等指标，建立站点性能基线。
分析第三方资源影响：结合资源 URL、发起方和加载时长，评估广告、统计脚本及外部组件对页面性能的影响。
支持技术 SEO 审计：将页面时序数据与抓取状态结合，发现页面并按页面类型或模板制定优化优级。

OnPage 瀑布流性能分析 ​

计费说明 ​

请求说明 ​

请求参数 ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

result 字段 ​

crawl_status 字段 ​

items 页面性能字段 ​

resources 资源字段 ​

location 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

实用场景 ​