LLM 提及目标指标（实时）

POST /v3/ai_optimization/llm_mentions/target_metrics/live

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

/v3/ai_optimization/llm_mentions/target_metrics/live

用于聚合统计请求 target 数组中指定或域名的 LLM 提及指标。返回结果会根据所选平台、地区和语言进行聚合。支持的平台：

google：Google AI Overview
chat_gpt：ChatGPT

请求使用 UTF-8 编码的 JSON 格式，并将任务对象放 JSON 数组中。每次调用平台限流以认证说明中的 30/60/120 次/分钟规则为准。单个任务的执行时间最长约为 120 秒。

计费说明

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。响应体中的 cost 字段表示任务成本，计费结果请以响应头返回的人民币金额为准。

请求参数

顶层参数

参数	类型	填	说明
`target`	array	是	目标实体数组，最多 10 个对象。每个对象只能一个 `domain` 或一个 `keyword`。
`location_name`	string	否	搜索地区的完整名称。与 `location_code` 二选一。
`location_code`	integer	否	搜索地区代码。与 `location_name` 二选一，默认值为 `2840`。
`language_name`	string	否	搜索语言的完整名称。与 `language_code` 二选一。
`language_code`	string	否	搜索语言代码。与 `language_name` 二选一，默认值为 `en`。
`platform`	string	否	目标平台，可选值：`chat_gpt`、`google`。未指定时返回两个平台的数据。
`initial_dataset_filters`	array	否	聚合前应用于原始提及数据的过滤条件，最多支持 8 个过滤条件。
`internal_list_limit`	integer	否	限制数组中的最大数量，适用于 `sources_domain` 和 `search_results_domain`。取值范围为 `1`–`10`，默认值为 `10`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

> 请求至少一个 search_filter 为 include 的域名实体或实体。

`target`

target 是由目标实体组成的数组，最多支持 10 个对象。每个实体对象以下之一：

domain
keyword

域名实体和实体均支持 search_filter。如果所有目标均设置为排除条件，则请求无效；至少需要一个条件的目标。

域名实体

参数	类型	填	说明
`domain`	string	是*	目标域名。当未指定 `keyword` 时填，最长 63 个字符。
`search_filter`	string	否	域名筛选方式：`include` 或 `exclude`，默认值为 `include`。
`search_scope`	array	否	域名搜索范围：`any`、`sources`、`search_results`，默认值为 `any`。
`include_subdomains`	boolean	否	是否目标域名的子域名，默认值为 `false`。

域名应填写为不带 https:// 和 www. 的形式，例如：

json

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

search_scope 取值说明：

any：所有可用范围
sources：LLM 回答中引用的来源域名
search_results：与 LLM 查询的搜索结果域名

> 当 search_scope 为 search_results 时 chat_gpt 平台提供数据。

实体

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

示例：

json

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

match_type 取值说明：

word_match：词匹。搜索与种子匹、且前后或中间词的结果。例如搜索 light，可匹 light bulb、light switch。
partial_match：部分匹。搜索指定字符序列的结果，即使该序列位于更长单词。例如搜索 light，可匹 lighting、highlight。

地区和语言

`location_name`

类型：string
可选
搜索地区的完整名称。
使用该字段时无需传 location_code。
未指定时默认使用 location_code: 2840。
可通过以下接口获取可用地区及名称：

/v3/ai_optimization/llm_mentions/locations_and_languages

> chat_gpt 支持 United States。

`location_code`

类型：integer
可选
搜索地区代码。
使用该字段时无需传 location_name。
默认值为 2840。
可通过以下接口获取可用地区代码：

/v3/ai_optimization/llm_mentions/locations_and_languages

> chat_gpt 支持地区代码 2840。

`language_name`

类型：string
可选
搜索语言的完整名称。
使用该字段时无需传 language_code。
未指定时默认使用 language_code: en。
可通过以下接口获取可用语言及名称：

/v3/ai_optimization/llm_mentions/locations_and_languages

> chat_gpt 支持 English。

`language_code`

类型：string
可选
搜索语言代码。
使用该字段时无需传 language_name。
默认值为 en。
可通过以下接口获取可用语言代码：

/v3/ai_optimization/llm_mentions/locations_and_languages

> chat_gpt 支持语言代码 en。

`platform`

类型：string
可选
可选值：
- chat_gpt
- google
未指定时，同时返回两个平台的数据。

> chat_gpt 支持美国地区和英语，即 location_code: 2840、language_code: en。

`initial_dataset_filters`

用于在聚合前筛选原始 LLM 提及数据，只让满足条件的数据参与最终统计。最多支持 8 个过滤条件，并需在多个条件之间指定逻辑运算。

支持的运算符：

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

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

示例：

json

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

完整过滤字段和表达式说明请参考：

/v3/ai_optimization/llm_mentions/filters

`internal_list_limit`

类型：integer
可选
用于限制以下数组的最大数量：
- sources_domain
- search_results_domain
最小值：1
最大值：10
默认值：10

`tag`

类型：string
可选
用户自定义任务标识，最长 255 个字符。
可用于在请求与响应之间匹任务。
返回位置：响应任务的 data.tag。

请求示例

cURL

bash

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

Python

python

import requests

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

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

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

response = requests.post(url, headers=headers, json=post_data, timeout=130)
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 response = await axios.post(
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/target_metrics/live",
  [
    {
      language_code: "en",
      location_code: 2840,
      platform: "chat_gpt",
      target: [
        {
          domain: "en.wikipedia.org",
          search_filter: "exclude",
        },
        {
          keyword: "bmw",
          search_scope: ["answer"],
          match_type: "partial_match",
        },
      ],
      initial_dataset_filters: [
        ["ai_search_volume", ">", 10],
      ],
      internal_list_limit: 10,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    timeout: 130000,
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    `请求失败，错误码：${response.data.status_code}，` +
    `错误信息：${response.data.status_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	任务结果数组。

完整错误码请参考：

/v3/appendix/errors

任务字段

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

`result` 字段

字段	类型	说明
`total_count`	integer	与请求的结果总数。本接口中始终为 `0`。
`offset`	integer	`items` 数组中被省略的提及对象数量。本接口中始终为 `0`。
`items_count`	integer	`items` 数组返回的结果数量。本接口中始终为 `0`。
`aggregated_metrics`	object	聚合后的 LLM 提及指标。
`items`	array/null	单个目标的详细结果。本接口中为 `null`。

`aggregated_metrics` 字段

按地区聚合：`location`

数组中的每个对象代表一个地区分组。

字段	类型	说明
`key`	integer	地区分组标识。
`mentions`	integer	该地区分组下的 LLM 提及总次数。
`ai_search_volume`	integer	该地区分组下提及数据的聚合 AI 搜索量。

按语言聚合：`language`

数组中的每个对象代表一种语言。

字段	类型	说明
`key`	string	语言分组标识。
`mentions`	integer	该语言分组下的 LLM 提及总次数。
`ai_search_volume`	integer	该语言分组下提及数据的聚合 AI 搜索量。

按平台聚合：`platform`

数组中的每个对象代表一个 AI 平台。

字段	类型	说明
`key`	string	平台分组标识，例如 `chat_gpt` 或 `google`。
`mentions`	integer	该平台下的 LLM 提及总次数。
`ai_search_volume`	integer	该平台下提及数据的聚合 AI 搜索量。

来源域名：`sources_domain`

返回与目标、且被 LLM 回答引用为来源的热门域名。

字段	类型	说明
`key`	string	来源域名。
`mentions`	integer	目标在该来源域名数据中的提及次数。
`ai_search_volume`	integer	该来源域名分组下的聚合 AI 搜索量。

搜索结果域名：`search_results_domain`

返回出现在与 LLM 查询的搜索结果中的热门域名。

字段	类型	说明
`key`	string	搜索结果域名。
`mentions`	integer	目标与该域名的提及次数。
`ai_search_volume`	integer	该域名分组下的聚合 AI 搜索量。

> 该字段适用于 chat_gpt。

品牌实体标题：`brand_entities_title`

返回与目标、并出现在 LLM 查询搜索结果中的品牌实体标题。

字段	类型	说明
`key`	string	品牌实体标题。
`mentions`	integer	目标与该品牌实体的提及次数。
`ai_search_volume`	integer	该品牌实体分组下的聚合 AI 搜索量。

> 该字段适用于 chat_gpt。

品牌实体类别：`brand_entities_category`

返回与目标、并出现在 LLM 查询搜索结果中的品牌实体类别。

字段	类型	说明
`key`	string	品牌实体类别。
`mentions`	integer	目标与该品牌实体类别的提及次数。
`ai_search_volume`	integer	该品牌实体类别分组下的聚合 AI 搜索量。

> 该字段适用于 chat_gpt。

总体指标：`total`

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

响应示例

json

{
  "version": "0.1.20260610",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "2.5853 sec.",
  "cost": 0.101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "2.4100 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "target_metrics",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "target_metrics",
        "language_code": "en",
        "location_code": 2840,
        "platform": "chat_gpt",
        "target": [
          {
            "domain": "en.wikipedia.org",
            "search_filter": "exclude"
          },
          {
            "keyword": "bmw",
            "search_scope": ["answer"],
            "match_type": "partial_match"
          }
        ],
        "initial_dataset_filters": [
          ["ai_search_volume", ">", 10]
        ],
        "internal_list_limit": 10
      },
      "result": [
        {
          "total_count": 0,
          "offset": 0,
          "items_count": 0,
          "aggregated_metrics": {
            "location": [],
            "language": [
              {
                "key": "en",
                "mentions": 26465,
                "ai_search_volume": 1203984
              }
            ],
            "platform": [
              {
                "key": "chat_gpt",
                "mentions": 26465,
                "ai_search_volume": 1203984
              }
            ],
            "sources_domain": [],
            "search_results_domain": [],
            "brand_entities_title": [],
            "brand_entities_category": [],
            "total": {
              "mentions": 26465,
              "ai_search_volume": 1203984
            }
          },
          "items": null
        }
      ]
    }
  ]
}

实用场景

统计品牌或在 ChatGPT、Google AI Overview 中的提及次数，评估品牌在生成式搜索中的可见度。
对比不同平台、地区和语言下的 AI 提及表现，定位 SEO覆盖不足的市场。
分析 LLM 回答引用的热门来源域名，发现可争取的媒体、行业站点和外链资源。
筛选高 AI 搜索量的提及记录，优优化更大潜在价值的和主题。
识别与目标的搜索结果域名及品牌实体，完善竞品监控和品牌舆分析。

LLM 提及目标指标（实时） ​

计费说明 ​

请求参数 ​

顶层参数 ​

target ​

域名实体 ​

实体 ​

地区和语言 ​

location_name ​

location_code ​

language_name ​

language_code ​

platform ​

initial_dataset_filters ​

internal_list_limit ​

tag ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

result 字段 ​

aggregated_metrics 字段 ​

按地区聚合：location ​

按语言聚合：language ​

按平台聚合：platform ​

来源域名：sources_domain ​

搜索结果域名：search_results_domain ​

品牌实体标题：brand_entities_title ​

LLM 提及目标指标（实时）

计费说明

请求参数

顶层参数

`target`

域名实体

实体

地区和语言

`location_name`

`location_code`

`language_name`

`language_code`

`platform`

`initial_dataset_filters`

`internal_list_limit`

`tag`

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

任务字段

`result` 字段

`aggregated_metrics` 字段

按地区聚合：`location`

按语言聚合：`language`

按平台聚合：`platform`

来源域名：`sources_domain`

搜索结果域名：`search_results_domain`

品牌实体标题：`brand_entities_title`