概览 - 提及次数

API + MCP

POST/v3/brand-radar/mentions-overview

Requests to this endpoint consume API units based on the prompts parameter: requests returning only custom prompt data are free, while requests including Ahrefs prompt data follow standard API unit pricing.

Every entity provided in brands (and competitors, when applicable) must include at least one value in names. Entities consisting only of url_groups are not supported here because mentions are matched against brand names.

请求正文

whereobject

筛选表达式。可识别以下列标识符（这与 select 参数可识别的标识符不同）。

selectarray<string>Required

要返回的字段列表。

Example:["field_a","field_b"]

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"]}]}

search_volume_typestring

AI 可见性报告将切换为 AI 调整后搜索量。它能更准确地估算各类聊天机器人和 AI 搜索平台上对 AI 回答的需求。其计算方式为：根据各 AI 平台相对于 Google 的估计使用量，对 Google 搜索量进行调整。该参数将于 2026 年 8 月 31 日弃用；此后所有请求都将使用新的 AI 调整后搜索量。

允许的值:ask_volumekeyword_volume

Default:ask_volume

countryarray<string>

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

允许的值:adaeafagaialamaoarasatauawazba…

Default:[]

report_idstring

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

promptsstring

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

允许的值:ahrefscustom

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

marketarray<string>

品牌细分市场列表。已于 2026-05-18 弃用，此参数将在该日期后不久失效。

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

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

outputstring

输出格式。

允许的值:jsoncsvxmlphp

响应

metricsarray<object>

brandstring

品牌名称（请求中提供的您的品牌或竞争对手品牌）。

no_tracked_brandsinteger

与指定市场相关的回答中未提及任何所提供品牌的预计提及次数（未指定 market 时该值为 0）。

only_competitors_brandsinteger

仅提及竞争对手品牌的回答带来的预计提及次数。

only_target_brandinteger

仅提及您的品牌的回答带来的预计提及次数。

target_and_competitors_brandsinteger

同时提及您的品牌和竞争对手品牌的回答带来的预计提及次数。

totalinteger

您的品牌的预计提及次数总计（包含 only_target_brand 和 target_and_competitors_brands）。

curl "https://api.ahrefs.com/v3/brand-radar/mentions-overview" \ -X POST \ -H "Authorization: Bearer $AHREFS_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data-raw '{ "where": {}, "select": ["field_a","field_b"], "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "search_volume_type": "ask_volume", "country": ["ad"], "report_id": "string", "prompts": "ahrefs", "data_source": ["chatgpt"], "market": ["string"], "competitors": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "brands": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "output": "json" }'

{ "metrics": [ { "brand": "string", "no_tracked_brands": 0, "only_competitors_brands": 0, "only_target_brand": 0, "target_and_competitors_brands": 0, "total": 0 } ] }