页面列表（OnPage Pages）

接口说明

/v3/on_page/pages 用于返回指定爬取任务中的页面列表，以及每个页面的站优化检查结果和页面表现指标。

通过本接口，你可以获取页面级别的详细数据，例如：

• 页面标题、描述、canonical、H 标签 -外链数量、图片/脚本/样式资源规模
• 页面加载性能与 Core Web Vitals 指标
• 页面质量、可读性、一致性评分
• 各类 On-Page SEO 检查项与告警
• 失效页、重定向页及资源文件的状态信息

接口地址

POST https://api.seermartech.cn/v3/on_page/pages

计费说明

调用本接口本身不会额外收费。 在任务创建后，你可以在接下来的 30 天获取该任务结果。

参考价约 ¥0.0000 / 次扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

使用前提

调用本接口前，需要通过 /v3/on_page/task_post 创建站点爬取任务，并在响应中获取任务 id。 本接口基于该 id 返回已抓取页面的列表和分析结果。

请求体

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

[
 {
 "id": "07131248-1535-0216-1000-17384017ad04",
 "limit": 10
 }
]

请求参数

字段	类型	说明
id	string	任务 ID。填。可从 /v3/on_page/task_post 的响应中获取。示例：07131248-1535-0216-1000-17384017ad04
limit	integer	返回页面的最大数量。可选，默认 100，最大 1000
offset	integer	结果偏移量。可选，默认 0，最大 2000000。例如设置为 10，将跳过前 10 条结果，返回后续页面
filters	array	结果过滤条件数组。可选，最多同时设置 8 个过滤条件；条件之间需使用逻辑运算符 and 或 or 连接
order_by	array	排序规则。可选。可使用与 filters 相同的字段进行排序，排序方式支持 asc 和 desc
search_after_token	string	后续翻页令牌。可选。适合单次获取 20,000 条结果时时
tag	string	自定义任务标识。可选，最多 255 个字符。便于将响应结果与业务侧任务对应

filters 支持的运算符

支持以下过滤运算符：

• regex
• not_regex
• <
• <=
• >
• >=
• =
• <>
• in
• not_in
• like
• not_like

说明：

• like 和 not_like 支持使用 % 匹任意长度字符串
• 多个条件之间需显式插 and 或 or

示例：

[
 ["resource_type", "=", "html"],
 "and",
 ["meta.scripts_count", ">", 40]
]

可用过滤字段单可参考 /v3/on_page/filters_and_thresholds/。

order_by 说明

排序规则格式为：

["字段名,asc"]

或：

["字段名,desc"]

单次请求最多可设置 3 条排序规则。 多条排序规则示例：

[
 "meta.content.plain_text_word_count,desc",
 "onpage_score,desc"
]

search_after_token 说明

当结果集很大时，建议使用 search_after_token 分批拉取，以请求时。

注意：

• search_after_token 会在每次响应中返回
• 后续请求传该值后，可继续获取同一任务的后续结果
• 如果请求中指定了 search_after_token，则参数与上一请求保持一致

---

响应结构

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

顶层字段

字段	类型	说明
version	string	API 当前版本
status_code	integer	接口整体状态码
status_message	string	接口整体状态说明
time	string	执行耗时，单位秒
cost	float	本次请求总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

建议对状态码和异常做完整处理，错误码可参考 /v3/appendix/errors。

tasks[] 字段

字段	类型	说明
id	string	平台任务唯一标识，UUID 格式
status_code	integer	任务状态码
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	爬取会话
crawl_status.max_crawl_pages	integer	任务设置时指定的最大爬取页数
crawl_status.pages_in_queue	integer	当前仍在队列中的页面数
crawl_status.pages_crawled	integer	已抓取页面数
total_items_count	integer	数据库中符合条件的总条数
items_count	integer	当前结果集返回条数
items	array	页面/资源明细列表

---

items[] 返回类型说明

根据抓取对象和页面状态不同，items 中可能返回以下资源类型：

• html：HTML 页面
• broken：失效页面
• redirect：重定向页面
• script：脚本资源
• image：图片资源
• stylesheet：样式表资源

以下为主要字段说明。

---

HTML 页面（resource_type = "html"）

基础字段

字段	类型	说明
resource_type	string	返回资源类型，固定为 html
status_code	integer	页面 HTTP 状态码
location	string	响应头中的 Location，用于表示重定向目标 URL
url	string	页面 URL
meta	object	页面数据
page_timing	object	页面加载时序指标
onpage_score	float	页面 On-Page 优化评分，满分 100
total_dom_size	integer	页面 DOM 总大小
custom_js_response	string / object / integer	自定义 JS 执行结果，前提是在 /v3/on_page/task_post 中设置了 custom_js
custom_js_client_exception	string	自定义 JS 执行错误信息
resource_errors	object	资源错误与告警
broken_resources	boolean	页面是否失效资源
broken_links	boolean	页面是否失效链接
duplicate_title	boolean	页面标题是否重复
duplicate_description	boolean	页面描述是否重复
duplicate_content	boolean	页面是否重复
click_depth	integer	从首页到该页面所需点击层级
size	integer	页面原始大小，单位字节
encoded_size	integer	编码后页面大小，单位字节
total_transfer_size	integer	压缩传输大小
fetch_time	string	资源抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
cache_control	object	缓存控制信息
checks	object	页面检查项结果
content_encoding	string	编码类型
media_type	string	媒体类型，如 text/html
server	string	服务器标识
is_resource	boolean	是否为单独资源文件
url_length	integer	URL 长度
relative_url_length	integer	相对路径长度
last_modified	object / null	最近修改时间信息

meta 字段

字段	类型	说明
title	string	页面标题
charset	integer	代码页，例如 65001
follow	boolean	页面 meta robots 是否爬虫跟踪页面中的链接
generator	string	generator标签
htags	object	H 标签汇总
description	string	meta description
favicon	string	页面 favicon 地址
meta_keywords	string	keywords标签
canonical	string	canonical URL
internal_links_count	integer	页面中的链数
external_links_count	integer	页面中的外链数
inbound_links_count	integer	指向该页面的站链接数
images_count	integer	图片数量
images_size	integer	图片总大小，字节
scripts_count	integer	脚本数量
scripts_size	integer	脚本总大小，字节
stylesheets_count	integer	样式表数量
stylesheets_size	integer	样式表总大小，字节
title_length	integer	标题长度
description_length	integer	描述长度
render_blocking_scripts_count	integer	阻塞渲染的脚本数量
render_blocking_stylesheets_count	integer	阻塞渲染的样式表数量
cumulative_layout_shift	float	CLS 指标，衡量页面布局稳定性
meta_title	string	页面 head 中的 meta title
content	object	页面分析
deprecated_tags	array	页面中的已废弃标签
duplicate_meta_tags	array	重复的 meta 标签
spell	object	拼写检查结果
social_media_tags	object	社交媒体标签，如 Open Graph、Twitter Card

meta.content 字段

字段	类型	说明
plain_text_size	integer	页面纯文本总大小，字节
plain_text_rate	integer	纯文本占页面总大小比例
plain_text_word_count	float	页面词数
automated_readability_index	float	Automated Readability Index
coleman_liau_readability_index	float	Coleman–Liau 指数
dale_chall_readability_index	float	Dale–Chall 可读性指数
flesch_kincaid_readability_index	float	Flesch–Kincaid 可读性指数
smog_readability_index	float	SMOG 可读性指数
description_to_content_consistency	float	description 与正文一致性，范围 0-1
title_to_content_consistency	float	title 与正文一致性，范围 0-1
meta_keywords_to_content_consistency	float	keywords 与正文一致性，范围 0-1

spell 字段

字段	类型	说明
hunspell_language_code	string	拼写检查语言代码
misspelled	array	拼写错误词数组
misspelled[].word	string	拼错的单词

page_timing 字段

字段	类型	说明
time_to_interactive	integer	TTI，可交互时间，毫秒
dom_complete	integer	页面及子资源加载完成时间，毫秒
largest_contentful_paint	float	LCP，最大绘制时间，毫秒
first_input_delay	float	FID，首次延迟，毫秒
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 的时间

resource_errors 字段

字段	类型	说明
errors	array	资源错误列表
warnings	array	资源告警列表

错误项字段：

字段	类型	说明
line	integer	发现错误的行号
column	integer	发现错误的列号
message	string	错误文本
status_code	integer	错误状态码

错误状态码可能值：

• 0 — 未识别错误
• 501 — HTML 解析错误
• 1501 — JS 解析错误
• 2501 — CSS 解析错误
• 3501 — 图片解析错误
• 3502 — 图片缩放值为 0
• 3503 — 图片大小为 0
• 3504 — 图片格式无效

告警状态码可能值：

• 0 — 未识别告警
• 1 — 存在 60 个同级子节点的节点
• 2 — DOM 树 1500 个节点
• 3 — HTML 深度 32 层

常见告警消息：

• "Has node with more than 60 childs."
• "Has more that 1500 nodes."
• "HTML depth more than 32 tags."

cache_control 字段

字段	类型	说明
cachable	boolean	页面是否可缓存
ttl	integer	缓存有效时长

---

checks 页面检查项

checks 对象大量布尔型站检查结果。以下为主要字段：

字段	类型	说明
no_content_encoding	boolean	页面未启用压缩
high_loading_time	boolean	页面加载时间是否 3 秒
is_redirect	boolean	页面是否发生 3XX 重定向
is_4xx_code	boolean	页面是否返回 4XX
is_5xx_code	boolean	页面是否返回 5XX
is_broken	boolean	页面是否异常，响应码小于 200 或大于 400
is_www	boolean	页面是否位于 www 子域名
is_https	boolean	页面是否使用 HTTPS
is_http	boolean	页面是否使用 HTTP
high_waiting_time	boolean	TTFB 是否 1.5 秒
has_micromarkup	boolean	页面是否微数据标记
has_micromarkup_errors	boolean	微数据标记是否有错误
no_doctype	boolean	页面是否缺少 <!DOCTYPE HTML>
canonical	boolean	页面是否为 canonical 页面
no_encoding_meta_tag	boolean	页面是否缺少编码声明
no_h1_tag	boolean	页面是否缺少或为空的 H1
https_to_http_links	boolean	HTTPS 页面是否链接到了 HTTP 页面
has_html_doctype	boolean	页面是否 HTML DOCTYPE
size_greater_than_3mb	boolean	页面大小是否 3MB
meta_charset_consistency	boolean	编码声明与字符集是否一致
has_meta_refresh_redirect	boolean	是否存在 meta refresh 跳转
has_render_blocking_resources	boolean	是否存在阻塞渲染资源
from_sitemap	boolean	资源是否来自站点 sitemap
redirect_chain	boolean	是否存在多重重定向
low_content_rate	boolean	纯文本占比是否低于 0.1
high_content_rate	boolean	纯文本占比是否高于 0.9
low_character_count	boolean	页面字符数是否少于 1024
high_character_count	boolean	页面字符数是否 256000
small_page_size	boolean	页面大小是否小于 1024 字节
large_page_size	boolean	页面大小是否 1MB
low_readability_rate	boolean	Flesch–Kincaid 可读性分是否低于 15
irrelevant_description	boolean	description 与正文是否不，阈值 0.2
irrelevant_title	boolean	title 与正文是否不，阈值 0.3
irrelevant_meta_keywords	boolean	keywords 与正文是否不，阈值 0.6
title_too_long	boolean	title 是否 65 字符
has_meta_title	boolean	页面是否存在 meta_title
title_too_short	boolean	title 是否少于 30 字符
deprecated_html_tags	boolean	是否含已废弃 HTML 标签
duplicate_meta_tags	boolean	是否存在重复 meta 标签
duplicate_title_tag	boolean	是否存在多个 title 标签
no_image_alt	boolean	是否存在缺少 alt 的图片
no_image_title	boolean	是否存在缺少 title 的图片
no_description	boolean	是否缺少 description
no_title	boolean	是否缺少 title
no_favicon	boolean	是否缺少 favicon
seo_friendly_url	boolean	URL 是否符合 SEO 友好规则
flash	boolean	页面是否含 Flash
frame	boolean	页面是否 frame / iframe / frameset
lorem_ipsum	boolean	页面是否 lorem ipsum 占位
has_misspelling	boolean	页面是否存在拼写错误；需在任务创建时启用 check_spell
seo_friendly_url_characters_check	boolean	URL 是否由大小写拉丁字母、数字和短横线组成
seo_friendly_url_dynamic_check	boolean	URL 是否不含动态参数
seo_friendly_url_keywords_check	boolean	URL 是否与标题语义一致
seo_friendly_url_relative_length_check	boolean	URL 相对路径长度是否不 120 字符
is_orphan_page	boolean	是否为孤儿页，即无站页面链接指向它
is_link_relation_conflict	boolean	是否同时收到 nofollow 和 dofollow 站链接
has_links_to_redirects	boolean	页面是否链接到会再次重定向的页面
canonical_chain	boolean	canonical 是否链式指向 canonical 页面
canonical_to_redirect	boolean	canonical 是否指向重定向页
canonical_to_broken	boolean	canonical 是否指向 4xx/5xx 页面
recursive_canonical	boolean	是否存在循环 canonical
content_encoding	string	编码类型
media_type	string	媒体类型
server	string	服务器标识

注意：多个检查项在 canonical = true 时返回有效判断结果。 is_orphan_page 需在 /v3/on_page/task_post 中设置 respect_sitemap = true 才可用。

---

失效页面（resource_type = "broken"）

失效页面返回的主要字段：

• resource_type
• status_code
• location
• url
• size
• encoded_size
• total_transfer_size
• fetch_time
• fetch_timing
• resource_errors
• cache_control
• checks
• content_encoding
• media_type
• server
• is_resource
• last_modified

checks、resource_errors、cache_control 等结构与 HTML 页面类似，但通常不会 meta、page_timing、onpage_score 等完整页面分析字段。

---

重定向页面（resource_type = "redirect"）

重定向页面的特点：

• url 表示源 URL
• location 表示目标 URL
• size 对于重定向资源通常为 0
• encoded_size 对于重定向资源通常为 0

常见字段：

• status_code
• total_transfer_size
• fetch_time
• fetch_timing
• resource_errors
• cache_control
• checks
• content_encoding
• media_type
• server
• is_resource
• last_modified

---

资源文件（script / image / stylesheet）

当首个抓取 URL 本身是脚本、图片或样式表资源时，才会显示这些资源类型。

资源通用字段

字段	类型	说明
resource_type	string	资源类型：script、image、stylesheet
meta	object	资源属性； image 类型可用
status_code	integer	资源所在页面或资源本身的状态码
location	string	重定向目标
url	string	资源 URL
size	integer	资源大小，字节
encoded_size	integer	编码后资源大小
total_transfer_size	integer	压缩传输大小
fetch_time	string	抓取时间
fetch_timing	object	资源抓取耗时
cache_control	object	缓存信息
checks	object	资源检查结果
resource_errors	object	资源错误和告警
content_encoding	string	编码类型
media_type	string	资源媒体类型
accept_type	string	预期资源类型
server	string	服务器标识
last_modified	object	最近修改时间信息

图片资源 meta

字段	类型	说明
alternative_text	string	图片 alt 文本
title	string	图片标题
original_width	integer	原始宽度，px
original_height	integer	原始高度，px
width	integer	展示宽度，px
height	integer	展示高度，px

资源 checks 常见字段

字段	类型	说明
no_content_encoding	boolean	未启用压缩
high_loading_time	boolean	加载是否 3 秒
is_redirect	boolean	是否发生重定向
is_4xx_code	boolean	是否返回 4xx
is_5xx_code	boolean	是否返回 5xx
is_broken	boolean	是否为失效资源
is_www	boolean	是否位于 www 子域
is_https	boolean	是否使用 HTTPS
is_http	boolean	是否使用 HTTP
is_minified	boolean	样式/脚本是否已压缩 stylesheet、script 可用
has_subrequests	boolean	样式/脚本是否子请求 stylesheet、script 可用
has_redirect	boolean	资源是否存在重定向，script、image 可用
original_size_displayed	boolean	图片是否按原始尺寸展示 image 可用
recursive_canonical	boolean	是否存在循环 canonical
canonical_chain	boolean	是否存在 canonical 链
canonical_to_redirect	boolean	canonical 是否指向重定向页
canonical_to_broken	boolean	canonical 是否指向异常页
has_links_to_redirects	boolean	是否链接到重定向页
is_orphan_page	boolean	是否为孤儿页
is_link_relation_conflict	boolean	是否存在 nofollow / dofollow 冲突
from_sitemap	boolean	是否来自 sitemap

accept_type 可能值

• any
• none
• image
• sitemap
• robots
• script
• stylesheet
• redirect
• html
• text
• other
• font

---

代码示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/on_page/pages" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "id": "07281559-0695-0216-0000-c269be8b7592",
 "filters": [
 ["resource_type", "=", "html"],
 "and",
 ["meta.scripts_count", ">", 40]
 ],
 "order_by": [
 "meta.content.plain_text_word_count,desc"
 ],
 "limit": 10
 }
]'

Python

import requests

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

payload = [
 {
 "id": "07281559-0695-0216-0000-c269be8b7592",
 "filters": [
 ["resource_type", "=", "html"],
 "and",
 ["meta.scripts_count", ">", 40]
 ],
 "order_by": [
 "meta.content.plain_text_word_count,desc"
 ],
 "limit": 10
 }
]

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

TypeScript

import axios from "axios";

const postData = [
 {
 id: "07281559-0695-0216-0000-c269be8b7592",
 filters: [
 ["resource_type", "=", "html"],
 "and",
 ["meta.scripts_count", ">", 40]
 ],
 order_by: [
 "meta.content.plain_text_word_count,desc"
 ],
 limit: 10
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/on_page/pages",
 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.20220627",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.8376 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "on_page",
 "function": "pages",
 "filters": [],
 "limit": 3,
 "target": "example.com",
 "max_crawl_pages": 10,
 "store_raw_html": true,
 "support_cookies": true,
 "load_resources": true
 },
 "result": [
 {
 "crawl_progress": "finished",
 "crawl_status": {
 "max_crawl_pages": 10,
 "pages_in_queue": 0,
 "pages_crawled": 10
 },
 "total_items_count": 3,
 "items_count": 3,
 "items": [
 {
 "resource_type": "html",
 "status_code": 200,
 "location": null,
 "url": "https://example.com/",
 "meta": {
 "title": "首页标题",
 "charset": 65001,
 "follow": true,
 "description": "页面描述",
 "canonical": "https://example.com/",
 "internal_links_count": 70,
 "external_links_count": 38
 },
 "page_timing": {
 "time_to_interactive": 812,
 "dom_complete": 812,
 "largest_contentful_paint": 0,
 "first_input_delay": 0,
 "connection_time": 13,
 "time_to_secure_connection": 17,
 "request_sent_time": 0,
 "waiting_time": 0,
 "download_time": 5,
 "duration_time": 35,
 "fetch_start": 0,
 "fetch_end": 35
 },
 "onpage_score": 98.17,
 "broken_resources": false,
 "broken_links": false,
 "click_depth": 0,
 "size": 241785,
 "fetch_time": "2022-06-28 12:51:45 +00:00",
 "checks": {
 "is_https": true,
 "canonical": true,
 "no_h1_tag": false,
 "duplicate_meta_tags": true,
 "seo_friendly_url": true,
 "from_sitemap": true
 },
 "content_encoding": "br",
 "media_type": "text/html",
 "server": "cloudflare",
 "is_resource": false,
 "url_length": 23,
 "relative_url_length": 1,
 "last_modified": {
 "header": null,
 "sitemap": null,
 "meta_tag": "2022-05-28 11:18:10 +00:00"
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理

建议至少处理以下层级的错误：

1. HTTP 层错误：如 4xx、5xx
2. 接口层错误：顶层 status_code 非 20000
3. 任务层错误：tasks[].status_code 非成功状态
4. 业务层异常：如任务 id 不存在、过滤参数错误、翻页参数不一致等

可通过以下字段定位问题：

• 顶层：status_code、status_message
• 任务层：tasks[].status_code、tasks[].status_message

错误码可参考 /v3/appendix/errors。

实用场景

• 筛选低质量页面：按 onpage_score、low_content_rate、low_character_count 等条件过滤页面，快速定位需要优优化的落地页。
• 排查技术 SEO 问题：识别 broken_links、is_4xx_code、redirect_chain、canonical_to_broken 等问题，降低抓取损耗并改善索引质量。
• 监控页面性能表现：结合 page_timing、largest_contentful_paint、high_loading_time 等指标，发现拖页面体验的资源或模板。
• 治理站重复问题：利用 duplicate_title、duplicate_description、duplicate_content、duplicate_meta_tags 等字段，批量发现重复页面与重复信息。
• 分析与标签一致性：基于 title_to_content_consistency、description_to_content_consistency、irrelevant_title 等指标，检查标题、描述失和页面主题偏移问题。