Skip to main content
GET
Brand Visibility
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
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

string
required
Your ScrapeBadger API key.

Query Parameters

string
required
The question to ask, typically a buyer-intent prompt like best web scraping API for e-commerce. Maximum 4,096 characters.
string
required
The brand name to look for in the answer, e.g. ScrapeBadger.
string
Your domain, e.g. scrapebadger.com. Used for cited, cited_urls and citation_rank.
string
Alternate spellings that also count as a mention of brand. Comma-separated on GET; a string[] on POST.
string
Competitor names to measure against, e.g. Bright Data,Oxylabs,Zyte. Comma-separated on GET; a string[] on POST.
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.
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.
string
default:"web"
Retrieval focus: web, scholar (academic sources) or social (discussions and forums).

Response

string
Echo of the prompt you sent.
string
Echo of the brand you tracked.
string | null
Echo of the domain you supplied.
boolean
Whether the brand (or any alias) appears in the answer.
integer
How many times the brand or its aliases appear.
integer | null
Character offset of the first mention in answer. null when absent.
number
1.0 = named at the very start of the answer, 0.0 = absent.
number
Brand mentions as a percentage of brand + competitor mentions.
boolean
Whether the brand’s domain is among the cited sources.
string[]
The cited URLs on the brand’s domain.
integer | null
1-based rank of the brand’s first cited URL among all citations.
CompetitorMention[]
One entry per competitor you named: name, mentioned, mention_count, first_position, cited, cited_urls.
string | null
Answer text around the first brand mention.
string
The full answer text.
Citation[]
The sources the answer references, same shape as /ask.
boolean
Whether Perplexity searched the web.
string | null
Which model answered.
string
The market that actually answered. Without strict_country it can differ from the country you asked for.
integer
End-to-end time in milliseconds.
number | null
Answer creation time as a Unix timestamp.
string | null
Answer creation time as an ISO-8601 UTC string.

Example

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:
If no exit in that market answers in time you get a 503, which is not billed. Retry later rather than dropping strict_country:
503 Response