Skip to main content
GET
Ask Perplexity
Ask the real perplexity.ai a question anonymously and get the answer back as JSON, plus every source Perplexity retrieved, which of those it cited, and the sub-queries it searched for. Accepts GET (query params) or POST (JSON body) with identical fields. Credits: 20
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. At volume, run asks asynchronously.

Authorization

string
required
Your ScrapeBadger API key.

Query Parameters

string
required
The question to ask. Maximum 4,096 characters. Each request is standalone, so include all the context you need here.
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).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).
boolean
default:"false"
Also return answer_html: the answer rendered as an HTML fragment, with each [n] citation linked to its source. See Answer HTML. Same price.
boolean
default:"false"
Also return raw: Perplexity’s own answer object, exactly as it sent it. See Raw response. Same price.

Response

string
Echo of the prompt you sent.
string
The answer text. Citation offsets index into this string.
string | null
The answer with its Markdown formatting.
Citation[]
The sources the answer actually references.
SearchResult[]
The full set Perplexity retrieved, cited or not. Same fields as Citation without the answer offsets, plus cited (boolean).
string[]
Distinct hostnames across the sources.
Perplexity’s suggested follow-up questions.
MediaItem[]
Images attached to the answer (url, title, source_url, thumbnail).
MediaItem[]
Videos attached to the answer, same shape.
boolean
Whether Perplexity searched the web for this answer.
boolean
true when the stream budget expired mid-answer, so answer is partial.
string[]
The sub-queries Perplexity sent to its search backend (its retrieval fan-out).
string
The phrase this answer’s web search ran under. For a prompt of up to 35 characters it is the prompt itself. For a longer prompt it is usually a shorter phrase made of the prompt’s own key words. See What was searched.
boolean
true when the search ran under your whole prompt, false when it ran under the shorter search_query_str. The answer is written for your whole prompt either way.
string
The retrieval focus used.
string | null
Which model answered. Reported, not requestable.
string | null
Perplexity’s id for this answer.
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
Length of answer in characters.
integer
Number of entries in citations.
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.
string
Only with html=true. The answer as an HTML fragment. See Answer HTML.
object | null
Only with raw=true. Perplexity’s final answer object as received. See Raw response.

Example

What was searched

Perplexity’s anonymous tier limits how long a search phrase can be. A prompt of up to 35 characters is searched exactly as you wrote it. A longer prompt is still answered in full, but its web search usually runs under a shorter phrase made of the prompt’s own key words: Every response tells you which case you got. search_query_str is the phrase that was searched, and whole_prompt is true when that phrase was your whole prompt:
Log both fields when you compare answers over time: two answers to the same prompt are only comparable search for search when their search_query_str matches. The phrase is built from the nouns, names and acronyms of your prompt, earlier words first. Question words and words such as best, which or recommend never enter it. To steer the search of a long prompt, name the topic with specific nouns near the start.

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 question that names no place, such as best dentist, gets an answer for the asker’s city. Without location, that is the exit’s city, so it changes between calls. Set location to keep those answers on one place:
Perplexity now answers for Tokyo. The response carries the value next to country:
An unknown city or a malformed lat,lng fails before any attempt is made. It is not billed:
400 Response

Answer HTML

Perplexity has no server-side HTML for an answer. Its website builds the answer page in the browser from a JSON stream, and that stream is what we read. With html=true we render the answer’s Markdown as HTML for you:
  • Formatting: headings, paragraphs, bold and italics, lists, tables, code and links, as Perplexity wrote them.
  • Citations: each [n] marker becomes a link to its source: <a class="citation" data-ref="n" href="https://source.example/page">[n]</a>. data-ref matches ref_index in citations.
  • Safe to embed: raw HTML inside the answer is dropped, and so are javascript: and data: links.
  • A fragment, not a page: no <html> or <body> and no styles. Wrap it in your own page and style a.citation as you like.

Raw response

With raw=true the response also carries raw: Perplexity’s final answer object exactly as its app API sent it. Every other field in the response is parsed from it. It includes the answer blocks (Markdown, web results, the search fan-out), related_queries, display_model, mode, thread_url_slug and status. Field names and shapes are Perplexity’s and can change without notice, so prefer the parsed fields when they cover what you need. The thread’s write token (read_write_token) is removed. It adds about 100 KB to the response, so ask for it only when you need it.

Run this asynchronously

Calls on this API can run in the background, so you don’t hold a connection open while they work. Add one of these to the call:
An async call is billed once, when it completes. See Async requests and webhooks for webhooks, signatures and the SDK helpers.

Ask at volume

To run thousands of asks, don’t hold a connection open for each one. Submit every ask with a callback and an idempotency key. Each submit returns 202 at once, and each answer arrives at your server as a signed webhook.
  1. Submit each ask with X-Callback-URL (or callback_url) and an Idempotency-Key made from your own job id. Store the request_id you get back with the job.
  2. Verify each delivery’s X-ScrapeBadger-Signature with your webhook secret.
  3. Deduplicate on request_id. Deliveries are at least once, so the same answer can arrive twice.
  4. Resubmit 5xx failures with a new key. A failed ask is not billed. Its old key would only replay the same failure. Don’t resubmit a 4xx: fix the request instead.

Submit

Resending a submit with the same key, after a timeout or a network error, is safe: you get the first ask’s 202 back with Idempotent-Replayed: true, and nothing is billed twice. A 429 on submit is not billed either; resend it later with the same key.
Keep async_wait at 0. A callback already means async_wait=0 unless you set a wait, and the webhook is sent either way. A wait only delays the 202. At volume it costs you an open connection per ask for up to that many seconds, so Perplexity’s answer time, not your rate limit, sets how fast you can submit.

Receive

The receiver checks the signature, skips repeats and answers before it does any work. A 2xx within 10 s counts as delivered. Anything slower is sent again.
See Async requests and webhooks for the full payload, retries, delivery status and the webhook secret.
Perplexity is non-deterministic. The same prompt can return different wording and different sources on each call. For tracking, sample on a schedule and aggregate.