Docs
搜索文档...⌘K

AI 响应

API + MCP
POST/v3/brand-radar/ai-responses

对此端点的请求会根据 prompts 参数消耗 API 单位：仅返回自定义提示数据的请求免费；包含 Ahrefs 提示数据的请求则按标准版 API 单位价格计费。

请求正文

selectarray<string>Required

要返回的字段列表。

Example:["field_a","field_b"]
whereobject

过滤表达式。支持以下列标识符（这与 select 参数支持的标识符不同）。

report_idstring

要使用的报告 ID。如果提供该参数，则其他参数将从报告中获取（品牌、竞争对手、市场、国家/地区、筛选条件）。如果提供了国家/地区或筛选条件，它们将覆盖报告中的对应值。你可以在 Ahrefs 的 Brand Radar 报告 URL 中找到它：https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

要搜索的品牌名称和网站列表。

Default:[]
At least one of names or url_groups is required
namesarray<string>

品牌/竞争对手的名称

Example:["ahrefs","ahrefs seo"]
url_groupsarray<object>
targetstring (domain)required

目标对象的域名

Example:ahrefs.com
scopestringrequired

目标对象的范围。

允许的值:urlpathdomainsubdomains
competitorsarray<object>

要搜索的竞争对手名称和网站列表。

Default:[]
At least one of names or url_groups is required
namesarray<string>

品牌/竞争对手的名称

Example:["ahrefs","ahrefs seo"]
url_groupsarray<object>
targetstring (domain)required

目标对象的域名

Example:ahrefs.com
scopestringrequired

目标对象的范围。

允许的值:urlpathdomainsubdomains
content_filterobject

可选短语，用于根据内容包含或排除结果。

includearray<string>

仅显示至少包含以下任一完全匹配短语的结果。

excludearray<string>

隐藏包含以下任一完全匹配短语的结果。

data_sourcearray<string>Required

聊天机器人模型列表。所有模型都可相互组合。claude 模块仅支持自定义提示词。
google_ai_overviews_keywords 和 google_ai_mode_keywords 模型报告的是基于 Google 搜索查询（关键词）而非提示词得出的 AI Overview / AI Mode 可见性。

允许的值:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords
countryarray<string>

两位字母国家/地区代码列表（ISO 3166-1 alpha-2）。

允许的值:adaeafagaialamaoarasatauawazba…
Default:[]
promptsstring

要使用的提示词类型。如果未指定，将同时使用两者。自定义提示词需要提供 report_id。

允许的值:ahrefscustom
limitinteger

要返回的结果数量。

Default:1000
datestring (date)

要搜索的日期，格式为 YYYY-MM-DD。

date_comparedstring (date)

用于与 date 对比的日期，格式为 YYYY-MM-DD。必须严格早于 date。设置后，报告将涵盖两天中任意一天被回答过的每个提示词，并且 status 字段会报告它们在两天之间的变化情况。仅在 date_compared 有回答、而在 date 没有回答的提示词会被标记为 lost，其余字段将描述它在 date_compared 的响应，因为在 date 没有对应响应。

order_by

如何对结果进行排序：按某一列排序，或者像 Brand Radar 中的“情绪”页面那样，按回答对某个品牌的评价方式排序。

用于对结果进行排序的列。

允许的值:relevancevolume
tags_filterobject

用于筛选提示词标签的表达式。必须提供 report_id。使用 筛选语法，但须遵守以下限制：唯一有效的字段名是 "tag"；有效运算符仅包括："eq"、"neq"、"substring"、"isubstring"、"phrase_match"、"iphrase_match"、"prefix"、"suffix"、"empty"；and 和 or 的最大嵌套深度为 2。

Example:{ "or": [ { "field": "tag", "is": [ "eq", "branded" ] }, { "field": "tag", "is": [ "eq", "competitor" ] } ] }
brand_filterobject

用于筛选品牌可见度的表达式，对应“Your brand”筛选器。brand_name 用于匹配回答是否提及你的品牌："mentioned" 或 "not_mentioned"。page_status 用于匹配 AI 对你网页的使用方式："cited"（AI 从你的网站检索了网页，并在回答中引用了这些网页）、"found_but_not_cited"（AI 从你的网站检索了网页作为潜在来源，但未在最终回答中引用），或 "not_found"（AI 未从你的网站检索到任何网页）。
使用 筛选语法，但须遵守以下限制：唯一有效的运算符是 "eq"；每个字段对应一个部分：可以提供单个值，也可以用 or 组合同一字段的多个值；使用顶层 and/or 连接 brand_name 和 page_status 部分。如果选择某个字段的所有值，请求会被拒绝，因为这会匹配所有内容（应改为省略该字段）。

Example:{ "and": [ { "field": "brand_name", "is": [ "eq", "mentioned" ] }, { "or": [ { "field": "page_status", "is": [ "eq", "cited" ] }, { "field": "page_status", "is": [ "eq", "found_but_not_cited" ] } ] } ] }
volume_rangeobject

用于按搜索量范围进行筛选。

frominteger
tointeger
changesobject

需要 date_compared。仅保留在此处所选方式之一发生变化的提示词。这三列之间为 OR 关系，每列内的取值之间也为 OR 关系，因此省略或为空的列不会对筛选产生任何影响，而完全为空的对象会保留每个提示词。

promptarray<string>

保留仅在两个日期中的某一个日期有回答的提示词（new、lost），或在两个日期都有回答的提示词（no_change）。

允许的值:newlostno_change
mentionsarray<string>

保留以下提示词：响应中提及的你自有品牌集合新增了品牌（new）、减少了品牌（lost），或在两个日期保持一致（no_change）。不考虑竞争对手。

允许的值:newlostno_change
citationsarray<string>

保留以下提示词：响应引用的你自有域名集合新增了域名（new）、减少了域名（lost），或在两个日期保持一致（no_change）。不考虑竞争对手。

允许的值:newlostno_change
sentiment_filterobject

用于筛选回答如何谈论你的品牌和竞争对手，类似 Brand Radar 中的情绪筛选器。使用包含三个字段的筛选器语法：

可用字段：
  • brand（必填）：来自 brands 或 competitors 的名称，配合 "eq"。
  • sentiment（可选）：positive、neutral、negative 或 mixed。使用 "eq" 时，品牌以该情绪被提及。使用 "neq" 时，品牌会以某种情绪被提及，但绝不会是这一种。使用 "empty" 时，品牌从未以情绪被提及（包括未提及该品牌的回答）。使用 not "empty" 时，品牌以某种情绪被提及。不指定 sentiment 时，任何提及该品牌的回答都匹配。
  • aspect（可选）：情绪所针对的方面，配合 "eq"：features_specs、performance_effectiveness、price_value、reputation_popularity、quality_reliability、design_comfort、usability_compatibility、availability_delivery、safety_health、service_support 或 general。
    每条规则只针对一个品牌：一个条件，或条件的 and 组合。要组合多条规则，请将每条规则分别放在各自的 and 中，然后用顶层的 and 或 or 将它们连接起来。
Example:{ "or": [ { "and": [ { "field": "brand", "is": [ "eq", "Adidas" ] }, { "field": "sentiment", "is": [ "eq", "negative" ] } ] }, { "and": [ { "field": "brand", "is": [ "eq", "Nike" ] }, { "field": "sentiment", "is": [ "eq", "positive" ] }, { "field": "aspect", "is": [ "eq", "price_value" ] } ] } ] }
opinions_firstboolean

将包含对已追踪品牌的正面、负面或混合提及的回答排在其他回答之前，并按相关性对每个组排序，方式与 Brand Radar 的情绪页面列表一致。仅适用于 order_by 为 relevance 的情况。

Default:false
outputstring

输出格式。

允许的值:jsonphp

响应

ai_responsesarray<object>
brand_sentimentarray<object>

回答中对已追踪品牌的每一次提及：先列出你的品牌，再按顺序列出竞争对手，并包含回答对其的表述方式。

brandstring

提及到的已追踪品牌。

sentimentstring or null

回答在此次提及时如何谈论该品牌。如不可用则为 null。

允许的值:positiveneutralnegativemixednull
aspectstring or null

此次提及所针对的内容，例如价格或质量。如不可用则为 null。

允许的值:features_specsperformance_effectivenessprice_valuereputation_popularityquality_reliabilitydesign_comfortusability_compatibilityavailability_deliverysafety_healthservice_supportgeneralnull
snippetstring or null

提及内容周围的句子。如果在回答中找不到，则为 null。

countrystring

问题的国家/地区。

data_sourcestring

生成该回答的聊天机器人模型。

funnel_stagestring or null

提示词的漏斗阶段。当没有可用的漏斗阶段时，为 null。

允许的值:awarenessconsiderationdecisionunclearnull
intentarray<string>

提示词的意图标签，包括其主要意图、子类型以及品牌/本地属性。空数组表示没有可用的意图标签。

允许的值:informationalnavigationaltransactionalbrandedcommercialcomparisonhow_tolocalopinionrecommendation
last_updatedstring (date)

数据最后更新的日期。

linksarray<object>

（10 单位）用于生成回答的链接。

urlstring
titlestring or null
questionstring

用户提出的问题。

responsestring

(10 单位) 模型的响应。

search_queriesarray<string>

聊天机器人为生成响应而用于查找信息的搜索查询。注意：如果 data_source 不包含 chatgpt 或 perplexity，该字段将始终为空。

statusstring or null

提示词在 date_compared 与 date 之间的变化情况。除非设置了 date_compared，否则为 null。new — 在 date 有回答但在 date_compared 没有。lost — 在 date_compared 有回答但在 date 没有；由于在 date 上没有响应，本行其余内容描述的是 date_compared 的响应。no_change — 两个日期都有回答，但这并不表示响应内容本身、其提及或其引用是否发生了变化。

允许的值:newlostno_changenull
tagsarray<string>

分配给该查询的标签。

volumeinteger

(10 单位) 预计月度搜索量。这基于我们对 Google 的估算，并将相关关键词的搜索量合并计算（当该问题出现在 People Also Ask 栏目中时）。