实时 LLM 提及多目标指标

POST /v3/ai_optimization/llm_mentions/multi_target_metrics/live

本接口使用 POST 方法，路径为：

/v3/ai_optimization/llm_mentions/multi_target_metrics/live

用于对请求中 targets 数组指定的多个或域名进行 LLM 提及分析，并自定义 key 聚合返回结果。每个 items素对应一个目标组，可用于比较不同品牌、产品或竞争对手在 AI 平台中的提及。

结果受以下参数影响：

platform：分析平台，可选 Google AI Overview 或 ChatGPT。
location_name / location_code：搜索地域。
language_name / language_code：搜索语言。
targets：分析的或域名目标组。

> 单个 Live 请求只能 1 个任务。接口当前最长执行时间约为 120 秒。平台限流以认证说明中的 30/60/120 次/分钟规则为准。

计费

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

请求说明

请求体使用 UTF-8 编码的 JSON。
POST 请求体是 JSON 数组，格式为 [{ ... }]。
targets 至少 2 个、最多 10 个目标组。
每个目标组的 key 最多 250 个字符。
每个目标组的 target 最多 10 个域名实体和/或实体。
请求中至少需要有一个 domain_entity 或 keyword_entity 的 search_filter 设置为 include。
chat_gpt 数据支持美国、英语环境。

请求参数

顶层参数

参数	类型	填	说明
`targets`	array	是	含目标实体及聚合键的数组。至少 2 个、最多 10 个目标组。
`location_name`	string	否	搜索地域的完整名称。使用该参数后无需传 `location_code`。默认使用代码 `2840`。
`location_code`	integer	否	搜索地域代码。使用该参数后无需传 `location_name`。默认值为 `2840`。
`language_name`	string	否	搜索语言的完整名称。使用该参数后无需传 `language_code`。默认使用英语。
`language_code`	string	否	搜索语言代码。使用该参数后无需传 `language_name`。默认值为 `en`。
`platform`	string	否	分析平台。可选值：`chat_gpt`、`google`。未指定时返回两个平台的数据。
`filters`	array	否	对聚合后的结果进行过滤。最多支持 8 个过滤条件。
`initial_dataset_filters`	array	否	在聚合前对原始提及数据进行过滤，以限制参与统计的记录。最多支持 8 个过滤条件。
`order_by`	array	否	结果排序规则。最多支持 3 条排序规则。
`limit`	integer	否	返回结果的最大数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量。默认值为 `0`，最大值为 `1000000`。需要跳过更多结果时，请使用 `search_after_token`。
`internal_list_limit`	integer	否	限制数组的数量，适用于 `sources_domain` 和 `search_results_domain`。取值范围为 `1`～`10`，默认值为 `5`。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会原样返回在响应的 `data` 对象中。

`targets` 参数

targets 是目标组数组。每个目标组一个用于分组的 key 和一个目标实体数组 target。

参数	类型	填	说明
`key`	string	是	结果分组键，同时作为该目标组的标签。最多 250 个字符。
`target`	array	是	目标实体数组。每个目标组最多 10 个域名或实体。

域名实体 `domain_entity`

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

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

实体 `keyword_entity`

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

匹方式说明：

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

示例：

json

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

地域与语言参数

地域和语言的可用值可通过以下接口查询：

/v3/ai_optimization/llm_mentions/locations_and_languages

限制条件：

chat_gpt 支持 United States 或地域代码 2840。
chat_gpt 支持 English 或语言代码 en。
location_name 与 location_code 二选一。
language_name 与 language_code 二选一。

过滤参数

filters 和 initial_dataset_filters 均使用条件数组表示过滤表达式。支持的运算符：

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

，like 和 not_like 支持使用 % 匹零个或多个字符。

示例：

json

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

多个条件之间需要使用逻辑运算符 and 或 or。每个过滤数组最多 8 个条件。

`order_by` 参数

排序字段可使用与 filters 相同的字段，并通过逗号指定排序方向：

asc：升序。
desc：降序。

示例：

json

[
  "total.mentions,desc",
  "total.ai_search_volume,desc"
]

单次请求最多设置 3 条排序规则，多条规则之间使用逗号分隔。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/multi_target_metrics/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "targets": [
        {
          "key": "chat_gpt",
          "target": [
            {
              "keyword": "chat gpt",
              "search_filter": "include"
            }
          ]
        },
        {
          "key": "claude",
          "target": [
            {
              "keyword": "claude",
              "search_filter": "include"
            }
          ]
        },
        {
          "key": "gemini",
          "target": [
            {
              "keyword": "gemini",
              "search_filter": "include"
            }
          ]
        },
        {
          "key": "perplexity",
          "target": [
            {
              "keyword": "perplexity",
              "search_filter": "include"
            }
          ]
        }
      ],
      "initial_dataset_filters": [
        ["ai_search_volume", ">", 10]
      ],
      "location_code": 2840,
      "language_code": "en",
      "platform": "google",
      "internal_list_limit": 5
    }
  ]'

Python

python

from seermartech import RestClient

client = RestClient("smt_live_YOUR_KEY")

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

try:
    response = client.post(
        "/v3/ai_optimization/llm_mentions/multi_target_metrics/live",
        post_data,
    )
    print(response)
except Exception as error:
    print(f"请求发生错误：{error}")

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/multi_target_metrics/live",
  [
    {
      targets: [
        {
          key: "chat_gpt",
          target: [{ keyword: "chat gpt", search_filter: "include" }],
        },
        {
          key: "claude",
          target: [{ keyword: "claude", search_filter: "include" }],
        },
        {
          key: "gemini",
          target: [{ keyword: "gemini", search_filter: "include" }],
        },
        {
          key: "perplexity",
          target: [{ keyword: "perplexity", search_filter: "include" }],
        },
      ],
      initial_dataset_filters: [["ai_search_volume", ">", 10]],
      location_code: 2840,
      language_code: "en",
      platform: "google",
      internal_list_limit: 5,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

// 处理响应数据
console.log(response.data);

响应结构

接口返回 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	请求 URL 路径。
`data`	object	创建任务时提交的参数。
`result`	array	任务结果数组。

完整状态码和错误信息请参考错误码文档。

结果字段

result 通常以下字段：

字段	类型	说明
`total_count`	integer	结果总数。
`offset`	integer	当前结果偏移量，与请求中的 `offset` 对应。
`items_count`	integer	`items` 数组中的数量。
`aggregated_metrics`	object	所有匹目标的整体聚合指标。
`items`	array	按请求中的 `key` 返回的各目标组指标。

`aggregated_metrics`

aggregated_metrics 汇总所有至少匹一个目标的 LLM 提及数据。

字段	类型	说明
`location`	array	按地域聚合的指标。
`language`	array	按语言聚合的指标。
`platform`	array	按 AI 平台聚合的指标。
`sources_domain`	array	LLM 回复中作为引用来源出现的主要域名。
`search_results_domain`	array	与 LLM 查询、出现在搜索结果中的主要域名。 `chat_gpt` 可用。
`brand_entities_title`	array	品牌实体标题。 `chat_gpt` 可用。
`brand_entities_category`	array	品牌实体分类。 `chat_gpt` 可用。
`total`	object	所有聚合维度的总提及数和 AI 搜索量。

`items`

items 中每个对应一个 targets 目标组。

字段	类型	说明
`key`	string	请求中提交的目标组聚合键。
`location`	array	按地域聚合的指标，`key` 为地域代码。
`language`	array	按语言聚合的指标，`key` 为语言代码。
`platform`	array	按平台聚合的指标，`key` 可为 `chat_gpt` 或 `google`。
`sources_domain`	array	LLM 回复引用的主要来源域名。
`search_results_domain`	array	LLM 查询搜索结果中的主要域名。
`brand_entities_title`	array	搜索结果的品牌实体标题。
`brand_entities_category`	array	搜索结果的品牌实体分类。
`total`	object	当前目标组的总提及数和 AI 搜索量。

聚合数组

location、language、platform、sources_domain、search_results_domain、brand_entities_title 和 brand_entities_category 中的通常以下字段：

字段	类型	说明
`key`	string / integer	当前聚合维度的标识。含义取决于数组类型：地域代码、语言代码、平台名称、域名、品牌标题或品牌分类。
`mentions`	integer	目标或域名在该聚合维度下被 LLM 提及的次数。
`ai_search_volume`	integer	当前的 AI 搜索量指标。

`total` 字段

字段	类型	说明
`mentions`	integer	目标或域名的 LLM 总提及次数。
`ai_search_volume`	integer	AI 搜索量总值。

响应示例

json

{
  "version": "0.1.20260610",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.5781 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.5000 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "multi_target_metrics",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "multi_target_metrics",
        "targets": [
          {
            "key": "chat_gpt",
            "target": [
              {
                "keyword": "chat gpt",
                "search_filter": "include"
              }
            ]
          },
          {
            "key": "audi",
            "target": [
              {
                "keyword": "audi",
                "search_filter": "include"
              }
            ]
          }
        ],
        "platform": "chat_gpt",
        "language_code": "en",
        "location_code": 2840,
        "limit": 5,
        "offset": 0,
        "internal_list_limit": 5
      },
      "result": [
        {
          "total_count": 2,
          "offset": 0,
          "items_count": 2,
          "aggregated_metrics": {
            "location": [],
            "language": [],
            "platform": [],
            "sources_domain": [],
            "search_results_domain": [],
            "brand_entities_title": [],
            "brand_entities_category": [],
            "total": {
              "mentions": 66067,
              "ai_search_volume": 1688821
            }
          },
          "items": [
            {
              "key": "chat_gpt",
              "location": [],
              "language": [],
              "platform": [],
              "sources_domain": [],
              "search_results_domain": [],
              "brand_entities_title": [],
              "brand_entities_category": [],
              "total": {
                "mentions": 52865,
                "ai_search_volume": 1379278
              }
            },
            {
              "key": "audi",
              "location": [],
              "language": [],
              "platform": [],
              "sources_domain": [],
              "search_results_domain": [],
              "brand_entities_title": [],
              "brand_entities_category": [],
              "total": {
                "mentions": 27157,
                "ai_search_volume": 649072
              }
            }
          ]
        }
      ]
    }
  ]
}

实用场景

比较多个品牌在 ChatGPT 或 Google AI Overview 中的提及次数，评估品牌在生成式搜索中的可见度差异。
筛选 AI 搜索量高于指定阈值的提及记录，优识别值得建设的高潜。
统计 LLM 回复引用的主要来源域名，定位竞争对手获得 AI 引用的来源。
分析品牌实体标题和分类的出现，发现 AI 平台对品牌的主要认知方向。
按地域、语言和平台拆分目标指标，为化 SEO 制定不同市场的和品牌优化策略。

实时 LLM 提及多目标指标 ​

计费 ​

请求说明 ​

请求参数 ​

顶层参数 ​

targets 参数 ​

域名实体 domain_entity ​

实体 keyword_entity ​

地域与语言参数 ​

过滤参数 ​

order_by 参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

结果字段 ​

aggregated_metrics ​

items ​

聚合数组 ​

total 字段 ​

响应示例 ​

实用场景 ​

实时 LLM 提及多目标指标

计费

请求说明

请求参数

顶层参数

`targets` 参数

域名实体 `domain_entity`

实体 `keyword_entity`

地域与语言参数

过滤参数

`order_by` 参数

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

任务字段

结果字段

`aggregated_metrics`

`items`

聚合数组

`total` 字段

响应示例

实用场景