AI 提及搜索（实时）

POST /v3/ai_optimization/llm_mentions/search/live

接口概述

/v3/ai_optimization/llm_mentions/search/live 用于实时获取 AI 搜索中的提及数据及指标。返回结果会受以下条件影响：

平台：google（Google AI Overview）或 chat_gpt
地区：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/search/live

计费说明

参考价请以参考单价换算，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

根据原文示例响应，单次请求成本示例为：

参考价约 ¥1.6480 / 次

说明：不同请求条件下成本会变化，最终以接口返回为准。

调用限制

每分钟最多可发起 2000 次 API 调用
每次 Live LLM Mentions 请求只能 1 个任务
任务执行时间目前最长可达 120 秒
POST 请求体为 UTF-8 编码的 JSON
请求体格式为 JSON 数组：[{ ... }]

请求参数

顶层参数

字段	类型	说明
`target`	array	填。目标实体数组，最多可传 `10` 个对象。每个对象只能一个 `domain` 或一个 `keyword` 及参数。
`location_name`	string	搜索地区名。传此字段时可不传 `location_code`。默认使用 `2840`。
`location_code`	integer	搜索地区代码。传此字段时可不传 `location_name`。默认值：`2840`。
`language_name`	string	搜索语言名。传此字段时可不传 `language_code`。默认使用 `en`。
`language_code`	string	搜索语言代码。传此字段时可不传 `language_name`。默认值：`en`。
`platform`	string	目标平台。可选值：`chat_gpt`、`google`。默认值：`google`。
`filters`	array	结果筛选条件数组。最多支持 `8` 个筛选条件。
`order_by`	array	排序规则数组。单次请求最多可设置 `3` 条排序规则。
`offset`	integer	返回结果中的偏移量。默认值：`0`，最大值：`9000`。
`search_after_token`	string	翻页令牌，用于获取后续结果。适合大结果集分页。
`limit`	integer	返回对象数量上限。默认值：`100`，最大值：`1000`。
`tag`	string	自定义任务标识，最大长度 `255` 字符。

`target` 对象说明

target 数组中的每个对象可以是：

域名实体（domain_entity）
实体（keyword_entity）

域名实体参数

字段	类型	说明
`domain`	string	目标域名。未指定 `keyword` 时填。最长 `63` 个字符；不要带 `https://` 和 `www.`。
`search_filter`	string	域名筛选方式。可选值：`include`、`exclude`。默认值：`include`。
`search_scope`	array	域名搜索范围。可选值：`any`、`sources`、`search_results`。默认值：`any`。
`include_subdomains`	boolean	是否该域名的子域名。默认值：`false`。

域名实体示例：

json

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

实体参数

字段	类型	说明
`keyword`	string	目标。未指定 `domain` 时填。最长 `250` 个字符。
`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`。

字段规则：

所有 %## 会被解码
字符 + 会被解码为空格
如果中需要使用 %，请写为 %25
如果中需要使用 +，请写为 %2B

match_type 说明：

word_match：按词匹，可匹前后附带词的完整短语例如搜索 light，可匹 light bulb、light switch
partial_match：按子串匹，可匹更长单词中的字符片段例如搜索 light，可匹 lighting、highlight

实体示例：

json

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

地区与语言限制

`chat_gpt` 平台限制

当 platform=chat_gpt 时支持：

地区：United States
location_code：2840
语言：English
language_code：en

`filters` 参数

用于按字段筛选返回结果。

最多支持 8 个筛选条件
条件之间可使用逻辑运算符：and、or
支持的比较运算符：

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

说明：

like 和 not_like 可合 % 通任意长度字符串

可用筛选字段请参考：

/v3/ai_optimization/llm_mentions/filters/

示例：

json

[
 ["ai_search_volume", ">", 1000]
]

`order_by` 参数

用于排序结果，字段写法与 filters 中的字段一致。

排序方向：
asc：升序
desc：降序
单次请求最多支持 3 条排序规则
多条规则用数组传递

示例：

json

["ai_search_volume,desc"]

`offset` 与 `search_after_token`

`offset`

默认值：0
最大值：9000

例如设置为 10 时，返回结果会跳过前 10 条提及记录。

`search_after_token`

适用于获取更深层分页结果，是总结果 20,000 条时，可降低时风险。

注意：

每次响应都会返回新的 search_after_token
下一次请求如果使用该值，则请求参数与前一次一致

响应结构

顶层响应字段

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

`tasks[]` 字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	任务成本，单位 USD
`result_count`	integer	`result` 数组数量
`path`	array	URL 路径
`data`	object	与请求中提交的参数一致
`result`	array	获取结果数组

`result[]` 字段

字段	类型	说明
`total_count`	integer	与请求匹的总结果数
`current_offset`	integer	当前 `items` 中已跳过的提及数
`search_after_token`	string	后续请求使用的分页令牌
`items_count`	integer	`items` 中返回的结果数量
`items`	array	提及数据

`items[]` 字段

字段	类型	说明
`platform`	string	请求中的平台
`model_name`	string	返回数据对应的 AI 模型名称
`location_code`	integer	请求中的地区代码
`language_code`	string	请求中的语言代码
`question`	string	问题
`answer`	string	回答，Markdown 格式
`sources`	array	模型最终回答中引用或依赖的数据源
`search_results`	array	模型检索到的网页搜索结果，重复项及未被最终使用的结果
`ai_search_volume`	integer	当前的 AI 搜索量指标
`monthly_searches`	array	月度 AI 搜索量趋势
`first_response_at`	string	首次记录该回答的时间，UTC 格式
`last_response_at`	string	最近更新该回答的时间，UTC 格式
`brand_entities`	array	回答中提到的品牌实体
`fan_out_queries`	array	为补主问题而衍生的查询

`sources[]` 字段

字段	类型	说明
`snippet`	string	来源描述
`source_name`	string	来源名称
`thumbnail`	string	来源缩略图
`markdown`	string	素的 Markdown 表示
`position`	integer	在结果中的位置
`title`	string	来源标题
`domain`	string	来源域名
`url`	string	来源链接
`publication_date`	string	发布时间，格式如 `2019-11-15 12:57:46 +00:00`

`search_results[]` 字段

字段	类型	说明
`description`	string	结果描述
`breadcrumb`	string	面屑路径
`position`	integer	排名位置
`title`	string	结果标题
`domain`	string	结果域名
`url`	string	结果链接
`publication_date`	string	发布时间，格式如 `2019-11-15 12:57:46 +00:00`

`monthly_searches[]` 字段

字段	类型	说明
`year`	integer	年份
`month`	integer	月份
`search_volume`	integer	当月 AI 搜索量指标

`brand_entities[]` 字段

字段	类型	说明
`position`	integer	位置
`title`	string	品牌名称
`category`	string	品牌分类

`fan_out_queries[]`

用于返回由主查询扩展出的问题，帮助理解 AI 回答的补搜索路径。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_name": "English",
 "location_code": 2840,
 "target": [
 {
 "domain": "example.com",
 "search_filter": "exclude"
 },
 {
 "keyword": "bmw",
 "search_scope": ["answer"]
 }
 ],
 "platform": "google",
 "filters": [
 ["ai_search_volume", ">", 1000]
 ],
 "order_by": [
 "ai_search_volume,desc"
 ],
 "offset": 0,
 "limit": 3
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 "language_name": "English",
 "location_code": 2840,
 "target": [
 {
 "domain": "example.com",
 "search_filter": "exclude"
 },
 {
 "keyword": "bmw",
 "search_scope": ["answer"]
 }
 ],
 "platform": "google",
 "filters": [
 ["ai_search_volume", ">", 1000]
 ],
 "order_by": [
 "ai_search_volume,desc"
 ],
 "limit": 3
 }
]

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

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
 "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search/live",
 [
 {
 language_name: "English",
 location_code: 2840,
 target: [
 {
 domain: "example.com",
 search_filter: "exclude"
 },
 {
 keyword: "bmw",
 search_scope: ["answer"]
 }
 ],
 platform: "google",
 filters: [
 ["ai_search_volume", ">", 1000]
 ],
 order_by: [
 "ai_search_volume,desc"
 ],
 offset: 0,
 limit: 3
 }
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 timeout: 120000
 }
);

console.log(response.data);

响应示例

json

{
 "version": "0.1.20251208",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.5640 sec.",
 "cost": 0.103,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.5401 sec.",
 "cost": 0.103,
 "result_count": 1,
 "path": [
 "v3",
 "ai_optimization",
 "llm_mentions",
 "search",
 "live"
 ],
 "data": {
 "api": "ai_optimization",
 "function": "search",
 "language_name": "English",
 "location_code": 2840,
 "target": [
 {
 "domain": "example.com",
 "search_filter": "exclude"
 },
 {
 "keyword": "bmw",
 "search_scope": ["answer"]
 }
 ],
 "platform": "google",
 "filters": [
 ["ai_search_volume", ">", 1000]
 ],
 "order_by": [
 "ai_search_volume,desc"
 ],
 "offset": 0,
 "limit": 3
 },
 "result": [
 {
 "total_count": 3,
 "current_offset": 0,
 "search_after_token": "eyJzb3J0IjpbMTUwMDAwMF19",
 "items_count": 3,
 "items": [
 {
 "platform": "google",
 "model_name": "google_ai_overview",
 "location_code": 2840,
 "language_code": "en",
 "question": "bmw",
 "answer": "Bayerische Motoren Werke 是 BMW 的称，回答为 Markdown 格式。",
 "sources": [
 {
 "snippet": "品牌介绍摘要",
 "source_name": "Wikipedia",
 "thumbnail": null,
 "markdown": null,
 "position": 1,
 "title": "BMW",
 "domain": "en.wikipedia.org",
 "url": "https://en.wikipedia.org/wiki/BMW",
 "publication_date": null
 }
 ],
 "search_results": null,
 "ai_search_volume": 1500000,
 "monthly_searches": [
 {
 "year": 2025,
 "month": 11,
 "search_volume": 1500000
 }
 ],
 "first_response_at": "2025-11-09 02:05:50 +00:00",
 "last_response_at": "2025-11-09 02:05:50 +00:00",
 "brand_entities": null,
 "fan_out_queries": null
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示整个请求的处理状态
tasks[].status_code 表示单个任务状态
建议同时校验：
HTTP 状态码
顶层 status_code
任务级 tasks[].status_code

常见成功状态：

状态码	说明
`20000`	请求成功

完整错误码体系请参考：

/v3/appendix/errors

建议在业务系统中实现完善的异常处理与重试机制，是在大结果集分页、时控制和参数校验场景下。

使用说明与注意事项

target 最多支持 10 个目标实体。
每个目标实体只能在 domain 和 keyword 中二选一。
如果使用 search_after_token，后续请求的参数与首次请求一致。
当分页偏移 9000 时，建议改用 search_after_token。
answer、sources、search_results 等字段适合用于分析 AI 回答来源、引用结构与品牌。
google 平台下，model_name 固定为 google_ai_overview。
chat_gpt 支持美国英文数据。

实用场景

监控品牌在 AI 回答中的：按品牌词或品牌域名检索 AI 回答中的提及，评估品牌在 AI 搜索中的可见度与声量。
分析竞品引用来源：排除自有域名后观察竞品在 sources 和 search_results 中的出现频率，识别对方在 AI 回答中的优势。
挖掘高价值 AI 问题：结合 ai_search_volume 和 monthly_searches 找出 AI 搜索热度高的问题，为选题和落地页建设提供依据。
评估被模型引用的机会：通过 sources、domain、publication_date 等字段分析哪些站点和类型更容易 AI 回答引用链路。
识别品牌联想与扩展问题：利用 brand_entities 和 fan_out_queries 查看模型如何品牌与问题，制定 AI SEO 与品牌策略。

AI 提及搜索（实时） ​

接口概述 ​

计费说明 ​

调用限制 ​

请求参数 ​

顶层参数 ​

target 对象说明 ​

域名实体参数 ​

实体参数 ​

地区与语言限制 ​

chat_gpt 平台限制 ​

filters 参数 ​

order_by 参数 ​

offset 与 search_after_token ​

offset ​

search_after_token ​

响应结构 ​

顶层响应字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段 ​

sources[] 字段 ​

search_results[] 字段 ​

monthly_searches[] 字段 ​

brand_entities[] 字段 ​

fan_out_queries[] ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

AI 提及搜索（实时）

接口概述

计费说明

调用限制

请求参数

顶层参数

`target` 对象说明

域名实体参数

实体参数

地区与语言限制

`chat_gpt` 平台限制

`filters` 参数

`order_by` 参数

`offset` 与 `search_after_token`

`offset`

`search_after_token`

响应结构

顶层响应字段

`tasks[]` 字段

`result[]` 字段

`items[]` 字段

`sources[]` 字段

`search_results[]` 字段

`monthly_searches[]` 字段

`brand_entities[]` 字段

`fan_out_queries[]`

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理