> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Brand Visibility

> Ask Perplexity a question and get an AEO/GEO analysis of how your brand appears in the answer: mentions, position, share of voice against competitors, and whether your domain was cited.

Ask **the real `perplexity.ai`** a buyer-intent question and get back both the
answer **and** how your brand fares in it: whether it was mentioned, how early,
how often, how it compares to named competitors, and whether your domain was
cited as a source.

Accepts `GET` (query params) or `POST` (JSON body).

**Credits:** 25

> [!WARNING]
>
> This is a live answer, not a cache. A call can take up to about 75 s while
> exits are tried, so set your client timeout to at least 90 s.

## Authorization

**X-API-Key** `string` *required*

Your ScrapeBadger API key.

## Query Parameters

**prompt** `string` *required*

The question to ask, typically a buyer-intent prompt like
`best web scraping API for e-commerce`. Maximum 4,096 characters.

**brand** `string` *required*

The brand name to look for in the answer, e.g. `ScrapeBadger`.

**domain** `string`

Your domain, e.g. `scrapebadger.com`. Used for `cited`, `cited_urls` and
`citation_rank`.

**aliases** `string`

Alternate spellings that also count as a mention of `brand`.
**Comma-separated on `GET`; a `string[]` on `POST`.**

**competitors** `string`

Competitor names to measure against, e.g. `Bright Data,Oxylabs,Zyte`.
**Comma-separated on `GET`; a `string[]` on `POST`.**

**country** `string`

ISO-3166 alpha-2 market, e.g. `US`, `DE`, `JP`. Sets the ask's language and
timezone (e.g. `DE`: `de-DE`, `Europe/Berlin`). Omit it and the market whose
exits answer best right now is used.

The egress is **best-effort**: when that market has no exit left, another one
carries the ask and the response `country` says which. Set `strict_country`
to forbid that.

**strict\_country** `boolean` (default: false)

Answer only from an exit in `country`, never another one. When no exit there
answers in time the call fails with **`503`** and
`detail.code = "country_unavailable"`. It is **not billed** (only `2xx`
responses are). Requires `country` — `400` otherwise. A JSON `boolean` on
`POST`.

**focus** `string` (default: web)

Retrieval focus: `web`, `scholar` (academic sources) or `social`
(discussions and forums).

## Response

**prompt** `string`

Echo of the prompt you sent.

**brand** `string`

Echo of the brand you tracked.

**domain** `string | null`

Echo of the domain you supplied.

**mentioned** `boolean`

Whether the brand (or any alias) appears in the answer.

**mention\_count** `integer`

How many times the brand or its aliases appear.

**first\_position** `integer | null`

Character offset of the first mention in `answer`. `null` when absent.

**position\_score** `number`

`1.0` = named at the very start of the answer, `0.0` = absent.

**share\_of\_voice\_pct** `number`

Brand mentions as a percentage of brand + competitor mentions.

**cited** `boolean`

Whether the brand's `domain` is among the cited sources.

**cited\_urls** `string[]`

The cited URLs on the brand's domain.

**citation\_rank** `integer | null`

1-based rank of the brand's first cited URL among all citations.

**competitors** `CompetitorMention[]`

One entry per competitor you named: `name`, `mentioned`, `mention_count`,
`first_position`, `cited`, `cited_urls`.

**excerpt** `string | null`

Answer text around the first brand mention.

**answer** `string`

The full answer text.

**citations** `Citation[]`

The sources the answer references, same shape as [`/ask`](https://docs.scrapebadger.com/api-reference/endpoint/perplexity/ask).

**web\_search\_triggered** `boolean`

Whether Perplexity searched the web.

**model** `string | null`

Which model answered.

**country** `string`

The market that actually answered. Without `strict_country` it can differ from the `country` you asked for.

**latency\_ms** `integer`

End-to-end time in milliseconds.

**created\_utc** `number | null`

Answer creation time as a Unix timestamp.

**created\_at** `string | null`

Answer creation time as an ISO-8601 UTC string.

## Example

```bash cURL theme={null}
curl -G "https://scrapebadger.com/v1/perplexity/brand-visibility" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "prompt=What is the best web scraping API for e-commerce data?" \
  --data-urlencode "brand=ScrapeBadger" \
  --data-urlencode "domain=scrapebadger.com" \
  --data-urlencode "competitors=Bright Data,Oxylabs,Zyte" \
  --data-urlencode "country=US" \
  --max-time 120
```

```python Python theme={null}
import requests

res = requests.post(
    "https://scrapebadger.com/v1/perplexity/brand-visibility",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "prompt": "What is the best web scraping API for e-commerce data?",
        "brand": "ScrapeBadger",
        "domain": "scrapebadger.com",
        "competitors": ["Bright Data", "Oxylabs", "Zyte"],
        "country": "DE",
        "strict_country": True,
    },
    timeout=120,
)
data = res.json()
print(data["country"], data["mentioned"], data["share_of_voice_pct"])
```

## Strict country

By default `country` is best-effort, so a market that is short of exits still
gets an answer, from another market. Check the response `country` to see which
one answered. When the market matters more than the answer (local rankings,
per-country visibility tracking), set `strict_country=true`:

```bash theme={null}
curl -G "https://scrapebadger.com/v1/perplexity/brand-visibility" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "prompt=best electricity provider" \
  --data-urlencode "brand=Octopus Energy" \
  --data-urlencode "country=DE" \
  --data-urlencode "strict_country=true" \
  --max-time 120
```

If no exit in that market answers in time you get a `503`, which is not billed.
Retry later rather than dropping `strict_country`:

```json 503 Response theme={null}
{
  "detail": {
    "code": "country_unavailable",
    "message": "no DE exit answered in 16 attempts {...}; strict_country never falls back to another country"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.