---
title: "Topics"
method: POST
path: "/brand-radar/topics"
tags: ["Brand Radar"]
---

# Topics

`POST /brand-radar/topics`

## Request

- Base URL: `https://api.ahrefs.com/v3`
- URL: `https://api.ahrefs.com/v3/brand-radar/topics`
- Auth: HTTP bearer

>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

- object
  - `select` string[], required: A list of fields to return. - `country` - `mentions` - `responses` - `topic` - `volume`
  - `where` object: The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter). **cited_domain**: The domain of a page that was used to generate the response. type: domain **cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match. type: string **cited_url_exact**: The URL of a page that was used to generate the response. type: string **cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match. type: string **question**: The question asked by the user. Note: the `substring` and `isubstring` operators are not supported on this field; use `phrase_match` or `iphrase_match` instead. type: string **response** (10 units): The response from the model. Note: the `substring` and `isubstring` operators are not supported on this field; use `phrase_match` or `iphrase_match` instead. type: string **response_entity**: An entity that the model recognized in its response. Note: the `substring` and `isubstring` operators are not supported on this field; use `phrase_match` or `iphrase_match` instead. type: string **response_entity_organisation**: An entity in the `organisation` category that the model recognized in its response. Note: the `substring` and `isubstring` operators are not supported on this field; use `phrase_match` or `iphrase_match` instead. type: string **response_entity_person**: An entity in the `person` category that the model recognized in its response. Note: the `substring` and `isubstring` operators are not supported on this field; use `phrase_match` or `iphrase_match` instead. type: string **response_entity_product**: An entity in the `product` category that the model recognized in its response. Note: the `substring` and `isubstring` operators are not supported on this field; use `phrase_match` or `iphrase_match` instead. type: string **search_queries**: The search query used by the chatbot to find information for the response. Note: if `data_source` does not include `chatgpt` or `perplexity`, this field will always be empty. Note: the `substring` and `isubstring` operators are not supported on this field; use `phrase_match` or `iphrase_match` instead. type: string **sponsored_advertiser**: The advertiser name shown on a sponsored result. type: string **sponsored_description**: The description of a sponsored result. type: string **sponsored_domain**: The domain of a sponsored result. type: domain **sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains. type: string **sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`. type: string **sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation. type: string **sponsored_title**: The title of a sponsored result. type: string **sponsored_url_exact**: The exact URL of a sponsored result. type: string **sponsored_url_prefix**: The URL prefix of a sponsored result. type: string **topic**: The topic of the query. Note: the `substring` and `isubstring` operators are not supported on this field; use `phrase_match` or `iphrase_match` instead. type: string
  - `report_id` string: 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#/...`
  - `brands` union[]: A list of brand names and websites to search for.
    - union
      - object
        - `names` string[], required: The names of the brand/competitor
        - `url_groups` object[]
          - `target` string, domain, required: The domain of the target
          - `scope` 'url' | 'path' | 'domain' | 'subdomains', required: Scope of the target.
      - object
        - `names` string[]: The names of the brand/competitor
        - `url_groups` object[], required
          - `target` string, domain, required: The domain of the target
          - `scope` 'url' | 'path' | 'domain' | 'subdomains', required: Scope of the target.
  - `competitors` union[]: A list of competitor names and websites to search for.
    - union
      - object
        - `names` string[], required: The names of the brand/competitor
        - `url_groups` object[]
          - `target` string, domain, required: The domain of the target
          - `scope` 'url' | 'path' | 'domain' | 'subdomains', required: Scope of the target.
      - object
        - `names` string[]: The names of the brand/competitor
        - `url_groups` object[], required
          - `target` string, domain, required: The domain of the target
          - `scope` 'url' | 'path' | 'domain' | 'subdomains', required: Scope of the target.
  - `content_filter` object: Optional phrases used to include or exclude results based on their content.
    - `include` string[]: Only show results containing at least one of these exact phrases.
    - `exclude` string[]: Hide results containing any of these exact phrases.
  - `data_source` 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.
  - `country` string[]: A list of two-letter country codes (ISO 3166-1 alpha-2).
  - `prompts` 'ahrefs' | 'custom': The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.
  - `limit` integer: The number of results to return.
  - `date` string, date: The date to search for in YYYY-MM-DD format.
  - `date_from` string, date: The start date of the historical period in YYYY-MM-DD format.
  - `date_to` string, date: The end date of the historical period in YYYY-MM-DD format.
  - `tags_filter` object: A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.
  - `brand_filter` object: A filter expression for your brand's visibility, mirroring the "Your brand" filter. `brand_name` matches whether a response mentions your brand: `"mentioned"` or `"not_mentioned"`. `page_status` matches how the AI used your pages: `"cited"` (the AI retrieved pages from your site and referenced them in the answer), `"found_but_not_cited"` (the AI retrieved pages from your site as potential sources but did not reference them in the final answer), or `"not_found"` (the AI did not retrieve any pages from your site). Uses [filter syntax](https://docs.ahrefs.com/api/docs/filter-syntax) with the following restrictions: the only valid operator is `"eq"`; each field is one section: give a single value, or combine several values of the same field with `or`; join the `brand_name` and `page_status` sections with a top-level `and`/`or`. Selecting every value of a field is rejected, since it matches everything (omit the field instead).
  - `volume_range` object: The volume range to filter by.
    - `from` integer
    - `to` integer
  - `output` 'json' | 'php': The output format.

## Response `200`

OK

- BrandRadarTopics
  - `topics` object[]
    - `country` string: The country associated with the topic. When no parent topic was identified, this is the only selected country, or `all` if multiple or all countries were selected.
    - `mentions` object[]: Response counts for the tracked brand and each competitor.
      - `entity` string: The tracked brand or competitor.
      - `responses` integer: The number of AI responses that mention the entity.
    - `responses` integer: The number of AI responses associated with the topic.
    - `topic` string, nullable: The parent topic. Null when no parent topic was identified.
    - `volume` integer, nullable: The topic's estimated monthly search volume.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests
- `500`: Internal Error

## Changes

- **2026-10-04** `ac067edcbb5b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ahrefs/apis/ahrefs-api/changes/brand-radar/topics/post.md)

---

[API](https://skmtc.dev/ahrefs/apis/ahrefs-api.md) - [All operations](https://skmtc.dev/ahrefs/apis/ahrefs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ahrefs/apis/ahrefs-api/revisions/667fedfff126?raw)