AI Optimization / LLM Mentions / 可用筛选条件

GET /v3/ai_optimization/llm_mentions/available_filters

本文说明 AI Optimization LLM Mentions 接口可使用的筛选条件（filters），以及筛选表达式的组织方式。

筛选条件与 result 数组中的对象字段，使用时需要对应结果对象的字段路径来指定。 另外需要注意：order_by 不能使用以下字段类型作为排序规则：

• array.str
• array.num

本接口用于获取该能力支持的筛选字段列表。

接口说明

• 请求方式：GET
• 请求地址：https://api.seermartech.cn/v3/ai_optimization/llm_mentions/available_filters
• 计费：，不产生扣费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

你可以通过该接口获取完整的可用筛选字段单。返回结果会按可用端点分组，便于为不同查询接口构造 filters 参数。

响应结构

接口返回 JSON 数据，顶层 tasks 数组，每个任务中对应的结果信息。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表参考 /v3/appendix/errors
status_message	string	通用状态信息，完整列表参考 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	所有任务总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数
tasks_error	integer	tasks 数组中返回错误的任务数
tasks	array	任务数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors
status_message	string	任务状态信息，完整列表参考 /v3/appendix/errors
time	string	任务执行耗时，单位秒
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	含 GET 请求 URL 中传的参数
result	array	结果数组，可用于数据筛选的参数列表

filters 参数结构说明

以下说明在 AI Optimization LLM Mentions 任务中，如何设置 filters 参数。

filters 字段

字段名	类型	说明
filters	array	结果筛选参数数组；可选；最多可同时添加 8 个筛选条件

使用规则：

• 多个条件之间需要使用逻辑运算符：and 或 or
• 筛选表达式中使用 . 和 , 作为分隔符
• 每个筛选条件通常由以下三部分构成：
• $parameter_field
• $filter_operator
• $filter_value

$parameter_field

类型	说明
string	要筛选的字段名；当使用筛选时为填

在当前能力中，可用字段：

• platform
• location_code
• language_code
• ai_search_volume
• first_response_at
• last_response_at

$filter_operator

类型	说明
string	筛选运算符；当使用筛选时为填

按字段类型可用的运算符如下：

数值类型 num

可用运算符：

• <
• <=
• >
• >=
• =
• <>
• in
• not_in

字符串类型 str

可用运算符：

• match
• not_match
• like
• not_like
• ilike
• not_ilike
• in
• not_in
• =
• <>
• regex
• not_regex

时间类型 time

可用运算符：

• <
• <=
• >
• >=

时间使用 UTC 格式：

yyyy-mm-dd hh:mm:ss +00:00

示例：

2025-10-21 06:25:30 +00:00

$filter_value

类型	说明
num / string / bool / time	筛选值；当使用筛选时为填

补说明：

• 当运算符为 in 或 not_in 时，$filter_value须是数组
• regex 和 not_regex 支持使用字符串，并遵循 RE2 正则语法
• regex / not_regex 可填写的最大字符数为 1000

常见筛选写法说明

下面给出几类常见写法，便于快速构造任务请求中的 filters。

1）筛选指定平台

[
 ["platform", "=", "google_ai_overviews"]
]

2）筛选多个地区

[
 ["location_code", "in", [2840, 2826]]
]

3）筛选 AI 搜索量大于某个值

[
 ["ai_search_volume", ">", 100]
]

4）筛选最近时间范围的数据

[
 ["last_response_at", ">=", "2025-10-21 06:25:30 +00:00"]
]

5）组合条件

[
 ["platform", "=", "google_ai_overviews"],
 "and",
 ["language_code", "=", "en"],
 "and",
 ["ai_search_volume", ">=", 50]
]

请求示例

cURL

curl -X GET "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/available_filters" \
 -H "Authorization: Bearer smt_live_YOUR_KEY"

Python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/available_filters"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript

const url = "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/available_filters";

const response = await fetch(url, {
 method: "GET",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 },
});

const data = await response.json;
console.log(data);

响应示例

{
 "version": "0.1.20250828",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0625 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "ai_optimization",
 "function": "available_filters"
 },
 "result": []
 }
 ]
}

使用建议

• 调用本接口，确认目标端点支持的筛选字段
• 再在对应查询接口中构造 filters，字段名或类型不匹
• 如果需要复杂筛选，建议从单条件开始验证，再逐步增加 and / or 组合
• 若涉及时间条件，请统一转换为 UTC 时间后再传

错误码说明

通用状态码、任务状态码及状态消息，请参考容错误码说明：

• /v3/appendix/errors

实用场景

• 筛选高价值提及：按 ai_search_volume 过滤高热度主题，帮助团队优布局更有增长潜力的 AI 搜索话题。
• 限定特定国家或语言市场：通过 location_code、language_code 过滤目标市场数据，提升跨区域 SEO 策略的针对性。
• 锁定特定平台表现：按 platform 过滤不同 AI 展示来源，评估品牌或在特定 LLM/AI 搜索场景下的。
• 追踪新增或近期变化的数据：按 first_response_at、last_response_at 设置时间范围，快速识别最近新增或更新的提及结果。
• 构建自动化分析规则：通过本接口获取合法字段，再由系统动态生成 filters，降低任务错误率并提升批量分析效率。