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

接口说明

POST /v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live

本接口用于自定义聚合键，对请求中 targets 数组指定的或域名进行 LLM 提及数据聚合。响应结果中的每个 items素对应一个 aggregation_key，可用于横向比较多个品牌、产品、模型或竞争对象。

接口返回的数据受以下参数影响：

AI 平台：google 或 chat_gpt
搜索位置
搜索语言
目标或域名
初始数据筛选条件

> 接口状态说明
> 本接口属于旧版路径。新接建议使用 /v3/ai_optimization/llm_mentions/multi_target_metrics/live。当前路径在可预见时间仍会继续支持，暂未设置下线日期。

单次请求只能 1 个任务
targets须至少 2 组、最多 10 组目标
每组 target 最多 10 个域名和/或实体平台限流以认证说明中的 30/60/120 次/分钟规则为准接口调用
任务执行时间目前最长约为 120 秒
请求体使用 UTF-8 编码的 JSON 数组

请求地址

http

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

认证方式

请求头使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

计费说明

本接口按任务计费。参考价约 ¥0.73 / 任务，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

顶层参数

参数	类型	填	说明
`targets`	array	是	含多个目标集合及聚合键。至少 2 组，最多 10 组。
`location_name`	string	否	搜索位置的完整名称。使用此参数时无需传 `location_code`。
`location_code`	integer	否	搜索位置代码。使用此参数时无需传 `location_name`。默认值为 `2840`。
`language_name`	string	否	搜索语言的完整名称。使用此参数时无需传 `language_code`。
`language_code`	string	否	搜索语言代码。使用此参数时无需传 `language_name`。默认值为 `en`。
`platform`	string	否	目标 AI 平台，可选值：`google`、`chat_gpt`。默认值为 `google`。
`initial_dataset_filters`	array	否	在聚合前应用于原始提及数据的筛选表达式，最多 8 个条件。
`internal_list_limit`	integer	否	限制数组的最大数量，可作用于 `sources_domain` 和 `search_results_domain`。取值范围为 `1`–`10`，默认值为 `5`。
`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）。
> google 返回的数据取决于所选择的位置、语言和平台。

`targets` 参数

targets 是由多个目标集合组成的数组。每个目标集合以下字段：

参数	类型	填	说明
`aggregation_key`	string	是	用于结果分组和比较的自定义标签，最多 250 个字符。
`target`	array	是	当前聚合组中的目标实体数组，最多 10 个实体。

示例结构：

json

{
  "aggregation_key": "claude",
  "target": [
    {
      "keyword": "claude"
    }
  ]
}

域名实体

域名实体通过对象表示：

json

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

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

{
  "keyword": "bmw",
  "search_filter": "include",
  "search_scope": ["any"],
  "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。

中的编码字符会被解码：

%## 格式的编码会被解码
+ 会被解码为空格
如果需要 %，请写为 %25
如果需要 +，请写为 %2B

初始数据筛选条件

initial_dataset_filters 用于在聚合前筛选原始 LLM 提及数据，从而限制参与计算的记录范围。

每个条件通常由字段名、运算符和值组成，并可使用 and 或 or 连接多个条件。最多可设置 8 个筛选条件。

支持的运算符：

text

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

使用 like 或 not_like 时，可以使用 % 匹任意长度的字符串。

示例：

json

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

请求示例

JSON 请求体

json

[
  {
    "language_code": "en",
    "location_code": 2840,
    "platform": "google",
    "targets": [
      {
        "aggregation_key": "chat_gpt",
        "target": [
          {
            "keyword": "chat gpt"
          }
        ]
      },
      {
        "aggregation_key": "claude",
        "target": [
          {
            "keyword": "claude"
          }
        ]
      },
      {
        "aggregation_key": "gemini",
        "target": [
          {
            "keyword": "gemini"
          }
        ]
      },
      {
        "aggregation_key": "perplexity",
        "target": [
          {
            "keyword": "perplexity",
            "search_filter": "include"
          }
        ]
      }
    ],
    "initial_dataset_filters": [
      [
        "ai_search_volume",
        ">",
        10
      ]
    ],
    "internal_list_limit": 5,
    "tag": "llm-model-comparison"
  }
]

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/cross_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",
      "targets": [
        {
          "aggregation_key": "chat_gpt",
          "target": [
            {
              "keyword": "chat gpt"
            }
          ]
        },
        {
          "aggregation_key": "claude",
          "target": [
            {
              "keyword": "claude"
            }
          ]
        },
        {
          "aggregation_key": "gemini",
          "target": [
            {
              "keyword": "gemini"
            }
          ]
        },
        {
          "aggregation_key": "perplexity",
          "target": [
            {
              "keyword": "perplexity",
              "search_filter": "include"
            }
          ]
        }
      ],
      "initial_dataset_filters": [
        [
          "ai_search_volume",
          ">",
          10
        ]
      ],
      "internal_list_limit": 5
    }
  ]'

Python

python

import requests

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

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

post_data = [
    {
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "targets": [
            {
                "aggregation_key": "chat_gpt",
                "target": [{"keyword": "chat gpt"}],
            },
            {
                "aggregation_key": "claude",
                "target": [{"keyword": "claude"}],
            },
            {
                "aggregation_key": "gemini",
                "target": [{"keyword": "gemini"}],
            },
            {
                "aggregation_key": "perplexity",
                "target": [
                    {
                        "keyword": "perplexity",
                        "search_filter": "include",
                    }
                ],
            },
        ],
        "initial_dataset_filters": [
            ["ai_search_volume", ">", 10]
        ],
        "internal_list_limit": 5,
    }
]

response = requests.post(url, headers=headers, json=post_data)
response.raise_for_status()

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/cross_aggregated_metrics/live";

const requestBody = [
  {
    language_code: "en",
    location_code: 2840,
    platform: "google",
    targets: [
      {
        aggregation_key: "chat_gpt",
        target: [{ keyword: "chat gpt" }],
      },
      {
        aggregation_key: "claude",
        target: [{ keyword: "claude" }],
      },
      {
        aggregation_key: "gemini",
        target: [{ keyword: "gemini" }],
      },
      {
        aggregation_key: "perplexity",
        target: [
          {
            keyword: "perplexity",
            search_filter: "include",
          },
        ],
      },
    ],
    initial_dataset_filters: [
      ["ai_search_volume", ">", 10],
    ],
    internal_list_limit: 5,
  },
];

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 数据，主要结构如下：

json

{
  "version": "0.1.20251208",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "2.2428 sec.",
  "cost": 0.101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "2.2428 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "cross_aggregated_metrics",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "cross_aggregated_metrics",
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "targets": []
      },
      "result": [
        {
          "total": {
            "location": [],
            "language": [],
            "platform": [],
            "sources_domain": [],
            "search_results_domain": [],
            "brand_entities_title": [],
            "brand_entities_category": []
          },
          "items": [
            {
              "key": "chat_gpt",
              "location": [],
              "language": [],
              "platform": [],
              "sources_domain": [],
              "search_results_domain": [],
              "brand_entities_title": [],
              "brand_entities_category": []
            }
          ]
        }
      ]
    }
  ]
}

响应字段

顶层响应字段

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

结果字段

result 中两个主要对象：

字段	类型	说明
`total`	object	所有目标的整体聚合指标。
`items`	array	按 `aggregation_key` 返回的各目标聚合指标。

`items` 字段

字段	类型	说明
`key`	string	请求中提交的 `aggregation_key`。
`location`	array	按地理位置聚合的指标。
`language`	array	按语言聚合的指标。
`platform`	array	按 AI 平台聚合的指标。
`sources_domain`	array	LLM 响应中作为引用来源出现的热门域名。
`search_results_domain`	array	与 LLM 查询、出现在搜索结果中的热门域名。
`brand_entities_title`	array	与目标的品牌实体标题。
`brand_entities_category`	array	与目标的品牌实体分类。

total 对象与 items 相同的聚合维度，但统计范围为所有目标的整体数据。

聚合数组

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`。

各聚合维度说明：

location：按地理位置拆分提及数据
language：按语言拆分提及数据
platform：按 AI 平台拆分提及数据
sources_domain：统计 LLM 响应中被引用的来源域名
search_results_domain：统计与 LLM 查询的搜索结果域名
brand_entities_title：统计搜索结果中的品牌实体标题
brand_entities_category：统计搜索结果中的品牌实体分类

错误处理

建议同时检查以下字段：

顶层 status_code
顶层 status_message
tasks_error
每个任务中的 status_code
每个任务中的 status_message

当 status_code 不为 20000 时，应根据状态码和消息进行错误处理，并直接读取空的 result 数组。

实用场景

比较多个 AI 品牌或产品的 LLM 提及次数，评估不同竞品在生成式搜索中的可见度差异。
筛选 ai_search_volume 高于指定阈值的提及记录，优分析较高潜在搜索需求的主题。
识别 sources_domain 中频繁被引用的来源网站，挖掘可用于合作、外链建设和权威性提升的站点。
分析 search_results_domain 与品牌实体数据，定位影响 AI 查询结果的竞争网站、品牌类别和实体。
拆分不同位置、语言和 AI 平台的聚合指标，制定面向特定市场的 GEO/SEO优化策略。

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

接口说明 ​

请求地址 ​

认证方式 ​

计费说明 ​

请求参数 ​

顶层参数 ​

targets 参数 ​

域名实体 ​

实体 ​

初始数据筛选条件 ​

请求示例 ​

JSON 请求体 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

响应字段 ​

顶层响应字段 ​

tasks 任务字段 ​

结果字段 ​

items 字段 ​

聚合数组 ​

错误处理 ​

实用场景 ​

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

接口说明

请求地址

认证方式

计费说明

请求参数

顶层参数

`targets` 参数

域名实体

实体

初始数据筛选条件

请求示例

JSON 请求体

curl

Python

TypeScript

响应结构

响应字段

顶层响应字段

`tasks` 任务字段

结果字段

`items` 字段

聚合数组

错误处理

实用场景