Docs
Search docs...⌘K

Share of Voice

API + MCP
POST/v3/brand-radar/sov-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.

Request body

whereobject

The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the select parameter).

report_idstring

The ID of the report to use. If one is given, other parameters are taken from the report (brand, competitors, market, country, filters). If country or filters are provided, they override the ones in the report. You can find it in the URL of your Brand Radar report in Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

A list of brand names and websites to search for.

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

The names of the brand/competitor

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

The domain of the target

Example:ahrefs.com
scopestringrequired

Scope of the target.

Allowed values:urlpathdomainsubdomains
competitorsarray<object>

A list of competitor names and websites to search for.

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

The names of the brand/competitor

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

The domain of the target

Example:ahrefs.com
scopestringrequired

Scope of the target.

Allowed values:urlpathdomainsubdomains
content_filterobject

Optional phrases used to include or exclude results based on their content.

includearray<string>

Only show results containing at least one of these exact phrases.

excludearray<string>

Hide results containing any of these exact phrases.

data_sourcearray<string>Required

A list of chatbot models. All models can be combined with each other. claude module supports only custom prompts.
The google_ai_overviews_keywords and google_ai_mode_keywords models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.

Allowed values:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords
countryarray<string>

A list of two-letter country codes (ISO 3166-1 alpha-2).

Allowed values:adaeafagaialamaoarasatauawazba…
Default:[]
promptsstring

The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.

Allowed values:ahrefscustom
tags_filterobject

A filter expression for prompt tags. Requires report_id. Uses filter syntax with the following restrictions: the only valid field name is "tag"; the only valid operator are: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; maximum nesting depth of and, or is 2.

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

The output format.

Allowed values:jsoncsvxmlphp

Responses

metricsarray<object>
brandstring

Brand name (either your brand or a competitor provided in the request).

entity_typestring

Whether the row represents an aggregate, your target brand, or a competitor.

Allowed values:aggregatetargetcompetitor
share_of_voicenumber (float)

Estimated share of voice for your brand.