AI 优化：LLM 提及目标指标 Lite（实时）

POST /v3/ai_optimization/llm_mentions/target_metrics_lite/live

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

/v3/ai_optimization/llm_mentions/target_metrics_lite/live

Live LLM Mentions Target Metrics Lite 是目标指标接口的简化版本，用于统计请求中 target 数组指定的和域名在大语言模型（LLM）回答中的聚合提及指标。

结果取决于请求中指定的平台、位置和语言：

google：Google AI Overview
chat_gpt：ChatGPT

每次调用只能提交一个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准，单个请求的任务执行时间最长约为 120 秒。

请求体使用 UTF-8 编码的 JSON 格式，并且顶层结构为 JSON 数组：

json

[
  {
    "target": []
  }
]

计费说明

本接口的扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应中的 cost 字段（平台原始 USD 成本兼容字段）表示任务成本数值，扣费请以计费响应头为准。

请求参数

顶层参数

参数	类型	填	说明
`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	否	目标平台，可选值为 `chat_gpt`、`google`。未指定时返回两个平台的数据。
`initial_dataset_filters`	array	否	聚合前应用于原始提及数据的过滤条件，最多支持 8 个过滤条件。
`limit`	integer	否	`items` 数组最多返回的结果数量，取值范围为 `1` 至 `1000`，默认值为 `100`。
`order_by`	array	否	结果排序规则，最多设置 3 条排序规则。
`offset`	integer	否	结果偏移量，默认值为 `0`，最大值为 `1000000`。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会在响应的 `data` 对象中原样返回。

`target`

target 是由目标实体组成的数组，最多 10 个对象。

每个目标实体可以是域名实体或实体：

json

{
  "target": [
    {
      "domain": "en.wikipedia.org",
      "search_filter": "exclude",
      "search_scope": ["any"]
    },
    {
      "keyword": "bmw",
      "search_filter": "include",
      "search_scope": ["answer"],
      "match_type": "partial_match"
    }
  ]
}

请求至少一个 domain 或 keyword 实体，并且至少有一个实体的 search_filter 设置为 include。

域名实体

域名实体用于分析指定域名是否出现在 LLM 提及数据中。

json

{
  "domain": "en.wikipedia.org",
  "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`。

实体

实体用于分析指定在 LLM 回答及数据中的提及。

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

match_type 支持以下取值：

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

位置与语言参数

可以使用名称或代码指定位置和语言，同一组参数中不要同时指定名称和代码。

位置

参数	类型	说明
`location_name`	string	搜索位置的完整名称。
`location_code`	integer	搜索位置代码，默认值为 `2840`。

chat_gpt 数据目前支持：

位置名称：United States
位置代码：2840

语言

参数	类型	说明
`language_name`	string	搜索语言的完整名称。
`language_code`	string	搜索语言代码，默认值为 `en`。

chat_gpt 数据目前支持：

语言名称：English
语言代码：en

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

/v3/ai_optimization/llm_mentions/locations_and_languages

平台参数

platform 用于指定需要返回数据的平台：

值	说明
`google`	Google AI Overview
`chat_gpt`	ChatGPT

如果不指定 platform，接口会返回两个平台的数据。需要注意，chat_gpt 支持美国位置和英语语言。

初始数据过滤器

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

最多可同时设置 8 个过滤条件。多个条件之间需要指定逻辑运算符 and 或 or。

支持的运算符：

=
<>
in
not_in
like
not_like
ilike
not_ilike
match
not_match

like 和 not_like 支持使用 % 匹任意数量的字符。

示例：

json

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

排序与分页

`limit`

限制 items 数组返回的数据量：

最小值：1
最大值：1000
默认值：100

`order_by`

用于设置结果排序，可使用过滤器支持的字段和表达式。排序格式为：

json

[
  "mentions,desc",
  "ai_search_volume,asc"
]

排序方向支持：

asc：升序
desc：降序

单次请求最多设置 3 条排序规则，多条规则使用数组分别表示。

`offset`

用于跳过结果数组开头的指定数量记录。

例如，设置为 10 时，将跳过前 10 条提及指标记录，从第 11 条开始返回。

默认值：0
最大值：1000000

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/target_metrics_lite/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"
          ]
        }
      ],
      "initial_dataset_filters": [
        [
          "ai_search_volume",
          ">",
          10
        ]
      ],
      "limit": 6
    }
  ]'

Python

python

import requests

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

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

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

response = requests.post(url, headers=headers, json=payload, timeout=120)
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/target_metrics_lite/live",
  [
    {
      language_code: "en",
      location_code: 2840,
      platform: "google",
      target: [
        {
          domain: "en.wikipedia.org",
          search_filter: "exclude",
        },
        {
          keyword: "bmw",
          search_scope: ["answer"],
        },
      ],
      initial_dataset_filters: [
        ["ai_search_volume", ">", 10],
      ],
      limit: 6,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    timeout: 120000,
  },
);

console.log(response.data);

响应结构

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

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。
`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	请求 URL 路径。
`data`	object	请求中提交的任务参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`total_count`	integer	与请求条件匹的结果总数。
`offset`	integer	`items` 数组中被跳过的结果数量。
`items_count`	integer	本次 `items` 数组返回的结果数量。
`aggregated_metrics`	object/null	聚合提及指标。在本接口中始终返回 `null`。
`items`	array	聚合提及指标数组。

`items` 字段

字段	类型	说明
`location`	integer	聚合指标对应的位置标识。
`language`	string	聚合指标对应的语言标识。
`platform`	string	聚合指标对应的 LLM 平台。
`metrics`	object	按指定目标及参数聚合后的 LLM 指标。

`metrics` 字段

字段	类型	说明
`mentions`	integer	目标被 LLM 提及的总次数。
`ai_search_volume`	integer	目标的聚合 AI 搜索量，即所有提及的 AI 搜索量总和。

响应示例

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.8501 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "target_metrics_lite",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "target_metrics_lite",
        "language_code": "en",
        "location_code": 2840,
        "platform": "google",
        "target": [
          {
            "domain": "en.wikipedia.org",
            "search_filter": "exclude"
          },
          {
            "keyword": "bmw",
            "search_scope": [
              "answer"
            ]
          }
        ],
        "limit": 6
      },
      "result": [
        {
          "total_count": 1,
          "offset": 0,
          "items_count": 1,
          "aggregated_metrics": null,
          "items": [
            {
              "location": 2840,
              "language": "en",
              "platform": "google",
              "metrics": {
                "mentions": 128,
                "ai_search_volume": 2450
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请根据顶层或任务级别的 status_code 和 status_message 处理异常：

顶层 status_code 表示本次 API 请求的整体状态。
任务级 status_code 表示任务的执行状态。
tasks_error 表示执行失败的任务数量。
建议对 HTTP 错误、参数校验错误、任务执行时和业务数据为空等分别处理。

实用场景

统计品牌在 AI 搜索结果中的提及次数，衡量品牌在 Google AI Overview 或 ChatGPT 中的可见度。
对比多个竞争对手域名的 LLM 提及表现，识别品牌与竞品在 AI 推荐场景中的差距。
筛选高 AI 搜索量，优发现值得优化和专题建设的搜索主题。
区分问题、回答和扩展查询中的提及，定位用户意图并优化 FAQ、产品页和知识库。
按国家、语言和平台拆分 AI 提及指标，支持化 SEO 和不同 AI 搜索平台的效果评估。

AI 优化：LLM 提及目标指标 Lite（实时） ​

计费说明 ​

请求参数 ​

顶层参数 ​

target ​

域名实体 ​

实体 ​

位置与语言参数 ​

位置 ​

语言 ​

平台参数 ​

初始数据过滤器 ​

排序与分页 ​

limit ​

order_by ​

offset ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

tasks 字段 ​

result 字段 ​

items 字段 ​

metrics 字段 ​

响应示例 ​

错误处理 ​

实用场景 ​

AI 优化：LLM 提及目标指标 Lite（实时）

计费说明

请求参数

顶层参数

`target`

域名实体

实体

位置与语言参数

位置

语言

平台参数

初始数据过滤器

排序与分页

`limit`

`order_by`

`offset`

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

`tasks` 字段

`result` 字段

`items` 字段

`metrics` 字段

响应示例

错误处理

实用场景