LLM 提及 Top Pages 实时接口

POST /v3/ai_optimization/llm_mentions/top_pages/live

接口说明

/v3/ai_optimization/llm_mentions/top_pages/live 用于按“被提及次数最高的页面”聚合返回指定 target 的 LLM 提及指标。

结果会基于以下维度限定：

平台：google（Google AI Overview）或 chat_gpt（ChatGPT）
地域：location_name / location_code
语言：language_name / language_code

可用地域与语言可通过 /v3/ai_optimization/llm_mentions/locations_and_languages 查询。

请求方式：POST
接口地址：https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_pages/live
请求体格式：JSON 数组 [{ ... }]
单次调用支持 1 个任务
频率限制：最高 2000 次调用/分钟
实时任务执行时间：当前最长可达 120 秒

计费说明

该接口按请求计费。参考价约 ¥1.6160 / 次。

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

请求参数

顶层参数

字段	类型	说明
`target`	array	填。目标实体数组，最多支持 10 个实体对象。每个实体只能一个 `domain` 或一个 `keyword`，以及参数。
`location_name`	string	搜索地域名。可选；填写后无需再传 `location_code`。默认使用 `2840`。可通过 `/v3/ai_optimization/llm_mentions/locations_and_languages` 获取支持列表。注意： `chat_gpt` 支持 `United States`。
`location_code`	integer	搜索地域编码。可选；填写后无需再传 `location_name`。默认值：`2840`。可通过 `/v3/ai_optimization/llm_mentions/locations_and_languages` 获取支持列表。注意： `chat_gpt` 支持 `2840`。
`language_name`	string	搜索语言名。可选；填写后无需再传 `language_code`。默认使用 `en`。可通过 `/v3/ai_optimization/llm_mentions/locations_and_languages` 获取支持列表。注意： `chat_gpt` 支持 `English`。
`language_code`	string	搜索语言编码。可选；填写后无需再传 `language_name`。默认值：`en`。可通过 `/v3/ai_optimization/llm_mentions/locations_and_languages` 获取支持列表。注意： `chat_gpt` 支持 `en`。
`platform`	string	目标平台。可选；可选值：`chat_gpt`、`google`。默认值：`google`。返回数据会随平台不同而变化。注意： `chat_gpt` 支持美国英文数据。
`links_scope`	string	链接来源范围。可选；指定用于提取页面和聚合数据的链接集合。可选值：`sources`、`search_results`。默认值：`sources`。
`initial_dataset_filters`	array	可选。在聚合前对原始提及数据集应用过滤条件，用于限制参与统计的行。最多支持 8 个过滤条件，条件之间需使用逻辑运算符 `and` / `or` 连接。
`items_list_limit`	integer	可选。返回 `items` 数组中的最大结果数。最小值：`1`；最大值：`10`；默认值：`5`。
`internal_list_limit`	integer	可选。限制数组数量。适用于：`sources_domain`、`search_results_domain`。最小值：`1`；最大值：`10`；默认值：`5`。
`tag`	string	可选。用户自定义任务标识，最长 255 个字符。便于请求与结果对账；响应中会在 `data` 对象里原样返回。

`target` 参数说明

target 是对象数组，最多可传 10 个实体。每个实体可以是“域名实体”或“实体”。

域名实体 `domain_entity`

示例：

json

{
 "domain": "en.wikipedia.org",
 "search_filter": "exclude",
 "search_scope": ["sources"]
}

字段	类型	说明
`domain`	string	目标域名。若未填写 `keyword`，则该字段填。最大 63 个字符；域名中不要带 `https://` 和 `www.`。
`search_filter`	string	域名搜索过滤方式。可选；可选值：`include`、`exclude`。默认值：`include`。
`search_scope`	array	域名搜索范围。可选；可选值：`any`、`sources`、`search_results`。默认值：`any`。
`include_subdomains`	boolean	是否将目标域名的子域纳搜索。可选；设为 `true` 时子域。默认值：`false`。

实体 `keyword_entity`

示例：

json

{
 "keyword": "bmw",
 "search_filter": "include",
 "search_scope": ["answer"],
 "match_type": "partial_match"
}

字段	类型	说明
`keyword`	string	目标。若未填写 `domain`，则该字段填。最大 250 个字符。`%##` 会被解码，`+` 会被解码为空格；若本身需要 `%`，请写为 `%25`；若需要 `+`，请写为 `%2B`。
`search_filter`	string	搜索过滤方式。可选；可选值：`include`、`exclude`。默认值：`include`。
`search_scope`	array	搜索范围。可选；可选值：`any`、`question`、`answer`、`brand_entities`、`fan_out_queries`。默认值：`any`。
`match_type`	string	匹方式。可选；可选值：`word_match`、`partial_match`。默认值：`word_match`。

`match_type` 说明

word_match：匹，以指定种子为核心，前后或中间出现额外词语
partial_match：匹中出现的或片段

`initial_dataset_filters` 说明

该参数用于在聚合前过滤原始提及数据库数据。

最多支持 8 个过滤条件
条件之间需显式写 and 或 or
支持的运算符：

=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match

like 与 not_like 支持 % 通符，表示匹任意长度字符串

示例：

json

[
 ["ai_search_volume", ">", 10]
]

可用过滤字段列表请参考 /v3/ai_optimization/llm_mentions/filters。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_pages/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "platform": "google",
 "target": [
 {
 "keyword": "bmw",
 "search_scope": ["answer"]
 },
 {
 "keyword": "auto",
 "search_scope": ["question"],
 "match_type": "partial_match"
 }
 ],
 "links_scope": "sources",
 "initial_dataset_filters": [
 ["ai_search_volume", ">", 10]
 ],
 "items_list_limit": 3,
 "internal_list_limit": 2
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_pages/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "platform": "google",
 "target": [
 {
 "keyword": "bmw",
 "search_scope": ["answer"]
 },
 {
 "keyword": "auto",
 "search_scope": ["question"],
 "match_type": "partial_match"
 }
 ],
 "links_scope": "sources",
 "initial_dataset_filters": [
 ["ai_search_volume", ">", 10]
 ],
 "items_list_limit": 3,
 "internal_list_limit": 2
 }
]

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

TypeScript

typescript

import axios from "axios";

async function run {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_pages/live",
 [
 {
 language_code: "en",
 location_code: 2840,
 platform: "google",
 target: [
 {
 keyword: "bmw",
 search_scope: ["answer"]
 },
 {
 keyword: "auto",
 search_scope: ["question"],
 match_type: "partial_match"
 }
 ],
 links_scope: "sources",
 initial_dataset_filters: [
 ["ai_search_volume", ">", 10]
 ],
 items_list_limit: 3,
 internal_list_limit: 2
 }
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
 }
 );

 console.log(response.data);
}

run.catch(console.error);

响应说明

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

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。完整错误码可参考 `/v3/appendix/errors`。建议在接时做好异常与错误处理。
`status_message`	string	通用状态信息。
`time`	string	执行耗时，单位秒。
`cost`	float	本次请求总费用，单位 USD。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数。
`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	URL 路径。
`data`	object	与请求中提交的参数一致。
`result`	array	结果数组。

结果字段说明

`result[].total`

聚合后的提及指标汇总，表示所有命中 Top Pages 的整体统计。

通用分组结构

以下字段会出现在多个分组数组中：

字段	类型	说明
`type`	string	素类型，固定为 `group_element`。
`key`	string	当前分组键值。
`mentions`	integer	LLM 提及总次数。
`ai_search_volume`	integer	当前的 AI 搜索热度指标。
`impressions`	integer	已废弃字段，固定返回 `null`。

汇总维度

字段	类型	说明
`location`	array	按地域分组的提及指标。
`language`	array	按语言分组的提及指标。
`platform`	array	按 AI 平台分组的提及指标。
`sources_domain`	array	与目标、在 LLM 回答中被引用为来源的域名列表。
`search_results_domain`	array	与目标、出现在搜索结果中的域名列表。
`brand_entities_title`	array	与目标、出现在 LLM 查询搜索结果中的品牌实体标题。
`brand_entities_category`	array	与目标、出现在 LLM 查询搜索结果中的品牌实体分类。
`items`	array	单个页面维度的详细结果。

`result[].items[]`

按页面返回的详细提及指标。

字段	类型	说明
`key`	string	命中的页面 URL。
`location`	array	该页面按地域分组的提及指标。
`language`	array	该页面按语言分组的提及指标。
`platform`	array	该页面按平台分组的提及指标。
`sources_domain`	array	与该页面、在 LLM 回答中被引用的来源域名。
`search_results_domain`	array	与该页面、出现在搜索结果中的域名。
`brand_entities_title`	array	与该页面的品牌实体标题。
`brand_entities_category`	array	与该页面的品牌实体分类。

说明：

sources_domain.key 表示来源域名
search_results_domain.key 表示搜索结果域名
brand_entities_title.key 表示品牌实体标题
brand_entities_category.key 表示品牌实体分类

这些数组中的每个同样：

type
key
mentions
ai_search_volume
impressions（已废弃，返回 null）

响应示例

json

{
 "version": "0.1.20251208",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "18.5294 sec.",
 "cost": 0.101,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "ai_optimization",
 "function": "top_pages",
 "language_code": "en",
 "location_code": 2840,
 "platform": "google",
 "target": [
 {
 "keyword": "bmw",
 "search_scope": ["answer"]
 },
 {
 "keyword": "auto",
 "search_scope": ["question"],
 "match_type": "partial_match"
 }
 ],
 "links_scope": "sources",
 "initial_dataset_filters": [
 ["ai_search_volume", ">", 10]
 ],
 "items_list_limit": 3,
 "internal_list_limit": 2
 },
 "result": [
 {
 "total": {
 "location": [],
 "language": [],
 "platform": [],
 "sources_domain": [],
 "search_results_domain": null,
 "brand_entities_title": null,
 "brand_entities_category": null
 },
 "items": [
 {
 "key": "https://www.caranddriver.com/rankings/best-sedans",
 "location": [],
 "language": [],
 "platform": [],
 "sources_domain": [],
 "search_results_domain": null,
 "brand_entities_title": null,
 "brand_entities_category": null
 },
 {
 "key": "https://cars.usnews.com/cars-trucks/advice/car-brands-available-in-america#:~:text=We've%20put%20together%20a,McLaren%2C%20and%20Rolls-Royce.",
 "location": [],
 "language": [],
 "platform": [],
 "sources_domain": [],
 "search_results_domain": null,
 "brand_entities_title": null,
 "brand_entities_category": null
 },
 {
 "key": "https://money.usnews.com/investing/articles/the-10-most-valuable-auto-companies-in-the-world",
 "location": [],
 "language": [],
 "platform": [],
 "sources_domain": [],
 "search_results_domain": null,
 "brand_entities_title": null,
 "brand_entities_category": null
 }
 ]
 }
 ]
 }
 ]
}

错误处理

请重点处理以下层级的状态信息：

顶层 status_code / status_message
tasks[].status_code / tasks[].status_message

当状态码非成功值时，建议：

记录完整请求参数与响应体
结合 /v3/appendix/errors 做错误码映射
对时、频控、参数错误分别设计重试或告警策略

使用建议

若你“LLM 回答引用了哪些来源页面”，优使用 links_scope: "sources"
若你“与 LLM 查询的搜索结果页面”，可使用 links_scope: "search_results"
若要控制返回体大小，可同时设置 items_list_limit 与 internal_list_limit
若只分析高价值提及样本，建议合 initial_dataset_filters 过滤低质量数据
若要做 ChatGPT 数据分析，请确保地域为美国、语言为英文

实用场景

识别品牌在 AI 回答中最常被引用的页面，帮助团队优优化高 URL。
对比不同触发的 Top Pages，发现哪些页面更容易 LLM 提及结果，指导专题页和集群建设。
过滤高 ai_search_volume 的提及页面，聚焦更业务价值的 AI 搜索流量机会。
分析来源域名与页面的，评估哪些外部站点正在影响品牌在 AI 场景中的可见性。
监控特定市场与语言下的页面表现，为化 SEO 和 AI 可见性优化提供依据。

LLM 提及 Top Pages 实时接口 ​

接口说明 ​

计费说明 ​

请求参数 ​

顶层参数 ​

target 参数说明 ​

域名实体 domain_entity ​

实体 keyword_entity ​

match_type 说明 ​

initial_dataset_filters 说明 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 数组字段 ​

结果字段说明 ​

result[].total ​

通用分组结构 ​

汇总维度 ​

result[].items[] ​

响应示例 ​

错误处理 ​

使用建议 ​

实用场景 ​

LLM 提及 Top Pages 实时接口

接口说明

计费说明

请求参数

顶层参数

`target` 参数说明

域名实体 `domain_entity`

实体 `keyword_entity`

`match_type` 说明

`initial_dataset_filters` 说明

请求示例

cURL

Python

TypeScript

响应说明

顶层响应字段

`tasks` 数组字段

结果字段说明

`result[].total`

通用分组结构

汇总维度

`result[].items[]`

响应示例

错误处理

使用建议

实用场景