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
A call can take up to about 75 s while exits are tried, so set your client timeout to at least 90 s. Every call renders a fresh answer: nothing is cached, so the same prompt sent again gets a new answer and is billed again.

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
Where the asker is. Perplexity answers a local question (best dentist, popular cafes, moving companies) for this place. Without it, that place is the exit’s city, which changes from call to call (a JP exit can be in Hamamatsu one call and Atsugi the next). Set it when you track a local prompt, so every sample is about the same place.A city from the list below, or lat,lng in decimal degrees (up to 8 decimal places), e.g. 35.6812,139.7671. Case does not matter, and spaces and underscores count as hyphens: New York and new_york both mean new-york. Any other value is a 400, not billed. A JSON string on POST.It does not change the egress. country still picks the exit and the answer language, so pair the two: country=JP&location=tokyo. Questions that are not local are unaffected.
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.
string | null
The location the ask was sent with, in canonical form, e.g. tokyo or 35.6812,139.7671. null when you did not set one.
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

Location

A local prompt, such as best dentist, gets an answer for the asker’s city. Without location, that is the exit’s city, so the brands named change with it between calls. Set location to track one place:
The response carries location next to country. An unknown city or a malformed lat,lng is a 400, which is not billed:
400 Response