页面性能瀑布图接口

POST /v3/on_page/waterfall

接口说明

该接口用于获取页面级性能瀑布图数据，可返回页面加载耗时、建立连接耗时、各类页面资源下载耗时等详细指标。

适用于搭建页面速度测试、网站性能诊断系统，以及 SEO 技术巡检场景中的页面体验分析。

• 请求方式：POST
• 接口地址：https://api.seermartech.cn/v3/on_page/waterfall

计费说明

该接口当前不额外收费；任务结果可在后续 30 天获取。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

所有 POST 数据均需使用 JSON（UTF-8 编码）提交。 请求体为 JSON 数组格式：

[
 {
 "id": "07281559-0695-0216-0000-c269be8b7592",
 "url": "https://example.com/page"
 }
]

请求参数

字段名	类型	填	说明
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	通用状态码。完整列表见 /v3/appendix/errors
status_message	string	通用状态信息。完整列表见 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	所有任务总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数
tasks	array	任务结果数组

建议在接时对状态码和异常场景做完整处理。

tasks 数组字段

字段名	类型	说明
id	string	本平台任务唯一标识，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	回显请求参数
result	array	结果数组

result 数组字段

字段名	类型	说明
crawl_progress	string	抓取会话状态，可选值：in_progress、finished
crawl_status	object	抓取会话详细状态
max_crawl_pages	integer	最大抓取页数，对应任务设置中的 max_crawl_pages
pages_in_queue	integer	当前抓取队列中的页面数量
pages_crawled	integer	已抓取页面数量
items_count	integer	结果项数量
items	array	页面性能结果列表

items 数组字段

字段名	类型	说明
page_url	string	页面 URL
time_to_interactive	integer	TTI（Time To Interactive），页面达到可交互状态所需时间，单位毫秒
dom_complete	integer	页面及所有子资源下载完成耗时，单位毫秒
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	资源在文档中的位置
is_render_blocking	boolean	是否为阻塞渲染资源

location 对象字段

字段名	类型	说明
line	integer	资源所在行号
offset_left	integer	资源在该行中的位置，即前置字符数，也可理解为列号；从 1 开始计数
offset_top	integer	资源距离 HTML 顶部的总字符偏移量

请求示例

cURL

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://example.com/tag/broken-links"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/waterfall"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 "id": "07281559-0695-0216-0000-c269be8b7592",
 "url": "https://example.com/tag/broken-links"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript

import axios from "axios";

const postData = [
 {
 id: "07281559-0695-0216-0000-c269be8b7592",
 url: "https://example.com/tag/broken-links"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/on_page/waterfall",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 // 返回页面瀑布图性能数据
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

下方为根据原始文档整理后的响应结构示例；字段以接口真实返回为准。

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1119 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "on_page",
 "function": "waterfall",
 "url": "https://example.com/help-center",
 "target": "example.com",
 "max_crawl_pages": 100,
 "load_resources": true
 },
 "result": [
 {
 "crawl_progress": "finished",
 "items_count": 1,
 "items": [
 {
 "page_url": "https://example.com/help-center",
 "time_to_interactive": 1840,
 "dom_complete": 2460,
 "connection_time": 120,
 "time_to_secure_connection": 95,
 "request_sent_time": 12,
 "waiting_time": 230,
 "download_time": 410,
 "duration_time": 772,
 "fetch_start": 15,
 "fetch_end": 425,
 "resources": [
 {
 "resource_type": "script",
 "url": "https://example.com/app.js",
 "initiator": "parser",
 "duration_time": 180,
 "fetch_start": 22,
 "fetch_end": 202,
 "location": {
 "line": 38,
 "offset_left": 5,
 "offset_top": 1240
 },
 "is_render_blocking": true
 }
 ]
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示本次请求的整体状态。
• tasks[].status_code 表示任务状态。
• 当存在异常、参数错误、认证失败或任务处理失败时，请结合 status_message 一并处理。
• 完整错误码定义参考：/v3/appendix/errors

建议重点处理以下：

• 请求参数缺失或格式错误
• id 无效，未能匹已创建任务
• url 不可访问或页面无法加载
• 抓取尚未完成，crawl_progress 为 in_progress
• 鉴权失败或访问频率受限

使用说明与注意事项

1. id 为填，需通过 /v3/on_page/task_post/ 创建对应任务后再调用本接口获取瀑布图数据。
2. url 也为填，应与目标页面保持一致，结果匹错误。
3. 若返回的 crawl_progress 为 in_progress，表示抓取仍在进行中，建议稍后重试。
4. resources 可用于定位资源、阻塞渲染资源以及文档中的资源位置，适合用于前端性能排查。
5. waiting_time、connection_time、time_to_secure_connection 等字段可识别网络、服务器响应或 TLS 建连瓶颈。

实用场景

• 诊断页面变原因：拆分连接、TLS、TTFB、下载等耗时，快速定位性能瓶颈来源。
• 识别阻塞渲染资源：分析 is_render_blocking 字段，找出影响首屏渲染的 JS/CSS 资源并指导优化。
• 监控核心落地页体验：定期采集重点 SEO 页面速度指标，及时发现改版、脚本更新或资源异常带来的性能回退。
• 排查第三方资源拖问题：查看 resources 明细，识别统计脚本、广告脚本、字体或外链资源导致的加载延迟。
• 支撑技术 SEO 审计报告：输出页面级与资源级耗时证据，为站点性能优化、抓取效率提升和用户体验改进提供依据。