实时 LLM 提及搜索

POST /v3/ai_optimization/llm_mentions/search_mentions/live

本接口用于实时获取 AI 搜索中的品牌、域名或提及数据，以及搜索结果和指标。结果会根据目标平台、搜索位置和语言返回：

google：Google AI Overview 数据
chat_gpt：ChatGPT 数据

请求方法与路径：POST /v3/ai_optimization/llm_mentions/search_mentions/live

请求使用 UTF-8 编码的 JSON 格式。平台限流以认证说明中的 30/60/120 次/分钟规则为准。单个任务最多 10 个目标实体。

> 任务执行时间最长约为 120 秒。

计费说明

原始文档未提供固定单价。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体是 JSON 数组，任务参数放在数组中：

json

[
  {
    "target": [
      {
        "domain": "example.com",
        "search_filter": "exclude"
      },
      {
        "keyword": "bmw",
        "search_scope": ["answer"]
      }
    ],
    "language_name": "English",
    "location_code": 2840,
    "platform": "google",
    "filters": [
      ["ai_search_volume", ">", 1000]
    ],
    "order_by": [
      "ai_search_volume,desc"
    ],
    "offset": 0,
    "limit": 3,
    "tag": "brand-monitoring-demo"
  }
]

顶层参数

参数	类型	填	说明
`target`	array	是	目标实体数组，最多 10 个实体对象。每个实体只能指定一个 `domain` 或一个 `keyword`。请求至少需要一个 `search_filter` 为 `include` 的域名实体或实体。
`location_name`	string	否	搜索位置的完整名称。指定后无需指定 `location_code`。未指定时默认使用 `location_code=2840`。
`location_code`	integer	否	搜索位置代码。指定后无需指定 `location_name`。默认值为 `2840`。
`language_name`	string	否	搜索语言的完整名称。指定后无需指定 `language_code`。未指定时默认使用 `language_code=en`。
`language_code`	string	否	搜索语言代码。指定后无需指定 `language_name`。默认值为 `en`。
`platform`	string	否	目标平台。可选值：`google`、`chat_gpt`。未指定时返回两个平台的数据。
`filters`	array	否	结果过滤条件，最多同时设置 8 个过滤条件。
`order_by`	array	否	结果排序规则，最多设置 3 条。
`offset`	integer	否	结果偏移量，默认值为 `0`，最大值为 `1000000`。
`search_after_token`	string	否	分页令牌，用于获取后续结果。使用该参数时，请求参数与上一次请求一致。
`limit`	integer	否	最多返回的结果对象数量，默认值为 `100`，最大值为 `1000`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中。

平台、位置和语言限制

chat_gpt 数据目前支持：

位置：United States，位置代码 2840
语言：English，语言代码 en

可通过以下接口查询可用的位置和语言：

text

GET /v3/ai_optimization/llm_mentions/locations_and_languages

`target` 参数

target 是目标实体的数组。每个实体是以下两种类型之一：

域名实体：domain_entity
实体：keyword_entity

域名实体

json

{
  "domain": "example.com",
  "search_filter": "exclude",
  "search_scope": ["any"],
  "include_subdomains": false
}

参数	类型	填	说明
`domain`	string	条件填	目标域名。不指定 `keyword` 时填，最长 63 个字符。域名中不要 `https://` 或 `www.`。
`search_filter`	string	否	域名过滤方式。可选值：`include`、`exclude`。默认值为 `include`。
`search_scope`	array	否	域名搜索范围。可选值：`any`、`sources`、`search_results`。默认值为 `any`。使用 `search_results` 时 `chat_gpt` 平台支持。
`include_subdomains`	boolean	否	是否目标域名的子域名。默认值为 `false`。

实体

json

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

参数	类型	填	说明
`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`。

`match_type` 匹方式

word_match：匹，可匹前后或短语单词的结果。例如搜索 light，可返回 light bulb、light switch。
partial_match：子字符串匹，只要结果指定字符序列即可。例如搜索 light，可返回 lighting、highlight。

过滤与排序

`filters`

过滤条件使用数组表示：

json

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

支持的运算符：

=
<>
in
not_in
like
not_like
ilike
not_ilike
match
not_match

多个过滤条件之间使用逻辑运算符 and 或 or。like 和 not_like 支持使用 % 匹任意长度的字符串。

示例：

json

[
  ["platform", "=", "google"],
  "and",
  ["ai_search_volume", ">", 1000]
]

`order_by`

排序规则使用“字段名,排序方向”的格式：

json

[
  "ai_search_volume,desc",
  "rank,asc"
]

排序方向支持：

asc：升序
desc：降序

单个请求最多设置 3 条排序规则，多个排序规则使用数组分隔。

分页参数

使用 `offset`

offset 用于跳过指定数量的结果。例如：

json

{
  "offset": 10,
  "limit": 100
}

表示跳过前 10 条结果，从后续结果开始返回。offset 最大值为 1000000。如果需要获取更多结果，建议使用 search_after_token，以减少请求时风险。

使用 `search_after_token`

响应中会返回 search_after_token。将该令牌用于下一次请求即可获取当前任务的后续结果：

json

{
  "search_after_token": "eyJzZWFyY2h..."
}

使用令牌时确保以下参数与上一次请求保持一致：

target
位置参数
语言参数
platform
filters
order_by
任务设置

每个后续任务都会生成唯一的 search_after_token。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search_mentions/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"
      ],
      "limit": 3
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search_mentions/live"

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

post_data = [
    {
        "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=post_data, timeout=150)
response.raise_for_status()

result = response.json()
print(result)

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search_mentions/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"],
      limit: 3,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    timeout: 150000,
  }
);

console.log(response.data);

响应结构

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

json

{
  "version": "0.1.20260610",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.5075 sec.",
  "cost": 0.103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.5070 sec.",
      "cost": 0.103,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "search_mentions",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "search_mentions",
        "language_name": "English",
        "location_code": 2840,
        "target": [
          {
            "keyword": "bmw",
            "search_filter": "include"
          }
        ],
        "platform": "google",
        "limit": 3
      },
      "result": [
        {
          "total_count": 3,
          "current_offset": 0,
          "search_after_token": "eyJzZWFyY2h...",
          "items_count": 3,
          "items": [
            {
              "platform": "google",
              "model_name": "google_ai_overview",
              "location_code": 2840,
              "language_code": "en",
              "question": "bmw",
              "answer": "AI 搜索生成的回答，使用 Markdown 格式返回。",
              "sources": [],
              "search_results": null,
              "ai_search_volume": 1500000,
              "monthly_searches": [],
              "first_response_at": "2025-11-09 04:05:50 +00:00",
              "last_response_at": "2026-05-14 18:17:26 +00:00",
              "brand_entities": null,
              "fan_out_queries": null,
              "is_web_search_based": true
            }
          ]
        }
      ]
    }
  ]
}

响应字段

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。成功时通常为 `20000`。
`status_message`	string	通用状态信息。
`time`	string	请求执行时间，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数。
`tasks`	array	任务结果数组。

`tasks` 字段

字段	类型	说明
`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	请求 API 路径。
`data`	object	本次 POST 请求中提交的任务参数。
`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 模型名称。对于 `google` 平台，固定为 `google_ai_overview`。
`location_code`	integer	请求中指定的位置代码。
`language_code`	string	请求中指定的语言代码。
`question`	string	问题或搜索。
`answer`	string	AI 生成的回答，使用 Markdown 格式。
`sources`	array	模型在最终回答中引用或依赖的来源。
`search_results`	array/null	模型检索到的网页搜索结果重复结果和未使用结果。 `chat_gpt` 支持。
`ai_search_volume`	integer	当前的 AI 搜索量指标。
`monthly_searches`	array	按月份统计的 AI 搜索量。
`first_response_at`	string	首次记录响应数据的时间，UTC 格式。
`last_response_at`	string	最近更新响应数据的时间，UTC 格式。
`brand_entities`	array/null	回答中提及的品牌实体。 `chat_gpt` 支持。
`fan_out_queries`	array/null	根据主查询扩展出的搜索查询。 `chat_gpt` 支持。
`is_web_search_based`	boolean	是否基于网页搜索生成回答。`true` 表示模型检索了实时网页结果，`false` 表示回答基于模型知识。

`sources` 字段

sources含模型引用或依赖的来源页面。

字段	类型	说明
`snippet`	string	来源页面摘要。
`source_name`	string	来源名称。
`thumbnail`	string/null	来源缩略图地址。
`markdown`	string/null	来源的 Markdown 表示。
`rank`	integer	来源在结果中的排名。
`title`	string	来源标题。
`domain`	string	来源域名。
`url`	string	来源 URL。
`publication_date`	string/null	发布时间，格式为 `YYYY-MM-DD HH:MM:SS +UTC偏移`，例如 `2019-11-15 12:57:46 +00:00`。

`search_results` 字段

该字段适用于 chat_gpt，表示模型为生成回答而检索到的网页搜索输出。

字段	类型	说明
`description`	string	搜索结果描述。
`breadcrumb`	string	页面面屑。
`rank`	integer	搜索结果排名。
`title`	string	搜索结果标题。
`domain`	string	搜索结果域名。
`url`	string	搜索结果 URL。
`publication_date`	string/null	搜索结果发布时间，格式为 `YYYY-MM-DD HH:MM:SS +UTC偏移`。

`monthly_searches` 字段

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	对应月份的 AI 搜索量。

`brand_entities` 字段

该字段适用于 chat_gpt，用于返回回答中识别到的品牌实体。

字段	类型	说明
`rank`	integer	品牌实体排名。
`title`	string	品牌名称。
`category`	string	品牌所属类别。

`fan_out_queries` 字段

该字段适用于 chat_gpt，从主查询扩展出的查询，用于帮助模型生成更的回答。字段结构以响应为准。

状态码与异常处理

请根据顶层和任务级别的 status_code 判断请求是否成功：

20000：请求成功
状态码：请求或任务执行异常

建议同时检查：

顶层 status_code
任务级 tasks[].status_code
tasks_error
status_message

完整错误码请参考错误码文档。

实用场景

监测品牌在 Google AI Overview 和 ChatGPT 中的提及，评估品牌在生成式搜索中的可见度。
对比竞争品牌的回答引用来源，识别可争取的外部权威页面和缺口。
筛选 AI 搜索量较高的，优优化高潜力问题页、产品页和知识库。
分析 question、answer 与 fan_out_queries，扩展 SEO主题和长尾问题覆盖范围。
结合 first_response_at 与 last_response_at 跟踪 AI 回答及引用来源的变化，支持生成式搜索效果复盘。

实时 LLM 提及搜索 ​

计费说明 ​

请求参数 ​

顶层参数 ​

平台、位置和语言限制 ​

target 参数 ​

域名实体 ​

实体 ​

match_type 匹方式 ​

过滤与排序 ​

filters ​

order_by ​

分页参数 ​

使用 offset ​

使用 search_after_token ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

响应字段 ​

顶层响应字段 ​

tasks 字段 ​

result 字段 ​

items 字段 ​

sources 字段 ​

search_results 字段 ​

monthly_searches 字段 ​

brand_entities 字段 ​

fan_out_queries 字段 ​

状态码与异常处理 ​

实时 LLM 提及搜索

计费说明

请求参数

顶层参数

平台、位置和语言限制

`target` 参数

域名实体

实体

`match_type` 匹方式

过滤与排序

`filters`

`order_by`

分页参数

使用 `offset`

使用 `search_after_token`

请求示例

cURL

Python

TypeScript

响应结构

响应字段

顶层响应字段

`tasks` 字段

`result` 字段

`items` 字段

`sources` 字段

`search_results` 字段

`monthly_searches` 字段

`brand_entities` 字段

`fan_out_queries` 字段

状态码与异常处理