LLM 提及聚合指标（实时，旧版）

本接口使用 POST /v3/ai_optimization/llm_mentions/aggregated_metrics/live，用于统计请求中 target 数组指定的或域名在大语言模型回答中的聚合提及指标。

> 容性说明 > > 本接口为旧版路径。新接建议使用 /v3/ai_optimization/llm_mentions/target_metrics/live。当前路径仍会继续支持，暂未设置停止服务日期。

返回结果取决于所选平台、位置和语言参数：

google：Google AI Overview
chat_gpt：ChatGPT

平台限流以认证说明中的 30/60/120 次/分钟规则为准。单个任务最多可 10 个目标实体。任务执行时间目前最长约为 120 秒。

接口信息

http

POST https://api.seermartech.cn/v3/ai_optimization/llm_mentions/aggregated_metrics/live

所有 POST 请求体使用 UTF-8 编码的 JSON 数组格式：

json

[
  {
    "target": [
      {
        "domain": "en.wikipedia.org",
        "search_filter": "exclude",
        "search_scope": ["sources"],
        "include_subdomains": false
      },
      {
        "keyword": "bmw",
        "search_filter": "include",
        "search_scope": ["answer"],
        "match_type": "word_match"
      }
    ],
    "location_code": 2840,
    "language_code": "en",
    "platform": "google",
    "internal_list_limit": 10
  }
]

计费说明

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

响应体中的 cost 字段为任务费用字段，金额请以平台扣费响应头为准。

请求参数

任务级参数

参数	类型	填	说明
`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	否	目标平台，可选 `google`、`chat_gpt`，默认值为 `google`。
`initial_dataset_filters`	array	否	在聚合前对原始提及数据应用的过滤条件，最多设置 8 个过滤条件。
`internal_list_limit`	integer	否	限制数组中的数量，适用于 `sources_domain` 和 `search_results_domain`。取值范围为 `1–20`，默认值为 `10`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

位置与语言限制

可以通过以下接口获取可用的位置和语言列表：

http

GET https://api.seermartech.cn/v3/ai_optimization/llm_mentions/locations_and_languages

chat_gpt 平台目前支持：

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

如果同时设置名称和编码，建议只保留一种，参数冲突。

`target` 目标实体

target 是目标域名或的数组，最多支持 10 个实体。

域名实体

每个域名实体可以以下字段：

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

示例：

json

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

实体

每个实体可以以下字段：

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

匹类型

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"
}

初始数据集过滤器

initial_dataset_filters 用于在聚合前过滤原始提及数据让符合条件的数据参与统计。

每个过滤条件通常表示为：

json

["字段名", "运算符", 值]

多个条件之间需要指定逻辑 and 或 or。最多支持 8 个过滤条件。

支持的运算符：

=
<>
in
not_in
like
not_like
ilike
not_ilike
match
not_match

对于 like 和 not_like，可以使用 % 匹任意长度的字符串空字符串。

示例：

json

{
  "initial_dataset_filters": [
    ["ai_search_volume", ">", 10]
  ]
}

完整过滤字段及表达式请参考过滤器说明。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/aggregated_metrics/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "platform": "google",
      "target": [
        {
          "domain": "en.wikipedia.org",
          "search_filter": "exclude"
        },
        {
          "keyword": "bmw",
          "search_scope": ["answer"],
          "match_type": "word_match"
        }
      ],
      "initial_dataset_filters": [
        ["ai_search_volume", ">", 10]
      ],
      "internal_list_limit": 10,
      "tag": "brand-monitoring-demo"
    }
  ]'

Python

python

import requests

url = (
    "https://api.seermartech.cn"
    "/v3/ai_optimization/llm_mentions/aggregated_metrics/live"
)

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

post_data = [
    {
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "target": [
            {
                "domain": "en.wikipedia.org",
                "search_filter": "exclude",
            },
            {
                "keyword": "bmw",
                "search_scope": ["answer"],
                "match_type": "word_match",
            },
        ],
        "initial_dataset_filters": [
            ["ai_search_volume", ">", 10],
        ],
        "internal_list_limit": 10,
    }
]

response = requests.post(url, headers=headers, json=post_data, timeout=130)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const url =
  "https://api.seermartech.cn" +
  "/v3/ai_optimization/llm_mentions/aggregated_metrics/live";

const requestBody = [
  {
    language_code: "en",
    location_code: 2840,
    platform: "google",
    target: [
      {
        domain: "en.wikipedia.org",
        search_filter: "exclude",
      },
      {
        keyword: "bmw",
        search_scope: ["answer"],
        match_type: "word_match",
      },
    ],
    initial_dataset_filters: [["ai_search_volume", ">", 10]],
    internal_list_limit: 10,
  },
];

axios
  .post(url, requestBody, {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  })
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应结构

接口返回 JSON 数据 tasks 数组。

顶层字段

字段	类型	说明
`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	任务结果数组。

任务字段

字段	类型	说明
`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	本次任务中提交的参数。
`result`	array	任务结果数组。

结果字段

result 数组中的结果对象主要以下字段：

字段	类型	说明
`total`	object	所有匹域名的 LLM 提及聚合指标汇总，按多个维度分组。
`items`	array/null	单个页面的详细提及指标。此旧版聚合接口中通常为 `null`。

分组通用字段

location、language、platform、sources_domain、search_results_domain、brand_entities_title 和 brand_entities_category 数组中的均使用以下结构：

字段	类型	说明
`type`	string	分组类型，固定为 `group_element`。
`key`	string	分组标识。含义取决于所在数组。
`mentions`	integer	LLM 提及总次数。
`ai_search_volume`	integer	当前 AI 搜索量指标。
`impressions`	integer/null	AI 展现量指标。该字段已废弃，返回值为 `null`。

`total.location`

按地理位置分组的提及指标数组。

key：地理位置分组标识
余字段遵循分组通用字段说明

`total.language`

按语言分组的提及指标数组。

key：语言分组标识
余字段遵循分组通用字段说明

`total.platform`

按 AI 平台分组的提及指标数组。

key：AI 平台分组标识
余字段遵循分组通用字段说明

`total.sources_domain`

与目标的主要来源域名数组，表示 LLM 回答中作为引用来源出现的域名。

key：被发现的来源域名
数组数量受 internal_list_limit 限制

`total.search_results_domain`

与 LLM 查询、出现在搜索结果中的主要域名数组。

key：被发现的搜索结果域名
数组数量受 internal_list_limit 限制

`total.brand_entities_title`

与目标的品牌实体标题数组。

key：被发现的品牌实体标题

`total.brand_entities_category`

与目标的品牌实体类别数组。

key：被发现的品牌实体类别

响应示例

json

{
  "version": "0.1.20251208",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.9593 sec.",
  "cost": 0.101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.9500 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "aggregated_metrics",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "aggregated_metrics",
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "target": [
          {
            "keyword": "bmw",
            "search_scope": ["answer"]
          }
        ],
        "internal_list_limit": 10
      },
      "result": [
        {
          "total": {
            "location": [
              {
                "type": "group_element",
                "key": "2840",
                "mentions": 12,
                "ai_search_volume": 100,
                "impressions": null
              }
            ],
            "language": [
              {
                "type": "group_element",
                "key": "en",
                "mentions": 12,
                "ai_search_volume": 100,
                "impressions": null
              }
            ],
            "platform": [
              {
                "type": "group_element",
                "key": "google",
                "mentions": 12,
                "ai_search_volume": 100,
                "impressions": null
              }
            ],
            "sources_domain": [
              {
                "type": "group_element",
                "key": "example.com",
                "mentions": 4,
                "ai_search_volume": 100,
                "impressions": null
              }
            ],
            "search_results_domain": null,
            "brand_entities_title": null,
            "brand_entities_category": null
          },
          "items": null
        }
      ]
    }
  ]
}

错误处理

请根据顶层或任务级别的 status_code 和 status_message 判断请求是否成功，并为网络异常、参数错误、任务执行失败等设计重试或告警机制。

顶层 status_code：表示整个请求的处理状态。
tasks[].status_code：表示单个任务的处理状态。
成功状态码通常为 20000。
完整错误码列表请参考错误码说明。

实用场景

监测品牌在 Google AI Overview 中的提及次数，按位置、语言和平台拆分结果，评估品牌在生成式搜索中的可见度。
对比目标域名与竞争域名的 LLM 提及表现，使用 search_filter 排除或纳指定域名，支持竞品声量分析。
识别 LLM 回答中的主要引用来源，读取 sources_domain 结果，指导团队优化被 AI 引用的页面和站点。
分析品牌实体标题与类别，读取 brand_entities_title 和 brand_entities_category，发现品牌在 AI 搜索中的实体和定位变化。
按 AI 搜索量筛选高价值提及数据，通过 initial_dataset_filters 聚焦高搜索量，提升 SEO 监测和报告的分析效率。

LLM 提及聚合指标（实时，旧版） ​

接口信息 ​

计费说明 ​

请求参数 ​

任务级参数 ​

位置与语言限制 ​

target 目标实体 ​

域名实体 ​

实体 ​

匹类型 ​

初始数据集过滤器 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

结果字段 ​

分组通用字段 ​

total.location ​

total.language ​

total.platform ​

total.sources_domain ​

total.search_results_domain ​

total.brand_entities_title ​

total.brand_entities_category ​

响应示例 ​

错误处理 ​

实用场景 ​

LLM 提及聚合指标（实时，旧版）

接口信息

计费说明

请求参数

任务级参数

位置与语言限制

`target` 目标实体

域名实体

实体

匹类型

初始数据集过滤器

请求示例

curl

Python

TypeScript

响应结构

顶层字段

任务字段

结果字段

分组通用字段

`total.location`

`total.language`

`total.platform`

`total.sources_domain`

`total.search_results_domain`

`total.brand_entities_title`

`total.brand_entities_category`

响应示例

错误处理

实用场景