Perplexity

Capture what Perplexity answers for a query. Captures are pulled from the live Perplexity app in a real browser, then normalized into the same canonical Envelope every surface returns, so the parser you write here works everywhere.

Enum

perplexity

Credits per capture

3 credits — charged only on success.

Every surface normalizes to the same Envelope. See Output formats.

Request

The simplest way to capture one Perplexity result is the alias POST /v1/search/perplexity — sync by default like any single-surface call — which accepts prompt (an alias of query) and a flat country.

curl https://api.aisearchapi.dev/v1/search/perplexity \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What are the best noise-canceling headphones in 2026?",
    "country": "US"
  }'

curl https://api.aisearchapi.dev/v1/search \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the best noise-canceling headphones in 2026?",
    "surfaces": ["perplexity"],
    "regions": [{ "country": "US" }]
  }'

const res = await fetch('https://api.aisearchapi.dev/v1/search/perplexity', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'What are the best noise-canceling headphones in 2026?',
    country: 'US',
  }),
});

const result = await res.json();
const envelope = result.children[0];
console.log(envelope.answer.markdown);
console.log(envelope.provenance.surfacePresent);

Both single-surface calls above run synchronously by default and return 200 with the parent id, rollup status, and the Envelope in children[0]. Add ?mode=async for the durable 202 + poll path.

Body fields

query

string

required

Your prompt, a non-empty string. On the /v1/search/perplexity alias you may send it as prompt instead.

surfaces

string[]

required

Must include "perplexity". On the alias endpoint the surface is fixed by the path, so you omit it.

regions

object[]

One capture per surface × region, at most 10 regions per request. Each entry is { country, state?, city?, language? }; country is an ISO-3166 alpha-2 code. Omitted: one untargeted (GLOBAL) capture. On the alias endpoint use the flat country field instead.

Response (trimmed Envelope)

A Perplexity capture returns the canonical four-section Envelope. Below it is trimmed to show the shape.

{
  "job": {
    "id": "job_8t2q.perplexity.us",
    "query": "What are the best noise-canceling headphones in 2026?",
    "surface": "perplexity",
    "region": "us",
    "status": "completed",
    "warnings": [],
    "requestedAt": "2026-06-27T00:00:00.000Z",
    "completedAt": "2026-06-27T00:00:04.500Z"
  },
  "provenance": {
    "model": {
      "providerId": null,
      "observedLabel": "Perplexity",
      "inferred": true,
      "confidence": 0.6
    },
    "webSearch": { "enabled": true, "known": true },
    "triggerState": "search",
    "persona": "anonymous_default_model",
    "loginState": "logged_out",
    "surfacePresent": true,
    "region": { "requested": "US", "effective": "US" },
    "capturedAt": "2026-06-27T00:00:04.000Z",
    "callUuid": "call_7a1f2e3d4c5b6a7988990a1b2c3d4e5f",
    "schemaVersion": "2026-06-27"
  },
  "answer": {
    "text": "For 2026, the standout noise-canceling headphones are the Sony WH-1000XM6 and the Bose QuietComfort Ultra...",
    "markdown": "For 2026, the standout noise-canceling headphones are the **Sony WH-1000XM6** and the **Bose QuietComfort Ultra**...",
    "blocks": [
      {
        "type": "paragraph",
        "text": "The Sony WH-1000XM6 leads on active noise cancellation.",
        "referenceIds": [0, 1]
      }
    ]
  },
  "evidence": {
    "sources": [
      {
        "id": 0,
        "url": "https://www.sony.com",
        "title": "Sony WH-1000XM6",
        "role": "cited",
        "cited": true,
        "charRanges": [[46, 61]]
      },
      {
        "id": 1,
        "url": "https://www.bose.com",
        "title": "Bose QuietComfort Ultra",
        "role": "cited",
        "cited": true,
        "charRanges": [[70, 92]]
      }
    ],
    "fanOut": { "provenance": "none", "queries": [] },
    "mentions": null,
    "shopping": null,
    "ads": null
  }
}

answer.markdown

string

Always populated. Use this as your rendering source of truth. answer.text carries the plain-text variant, and answer.blocks[] carry the answer as typed blocks.

evidence.sources

object[]

Cited and retrieved sources, each { id, url, title, role, cited, charRanges }; id is the integer that answer.blocks[].referenceIds point to. Perplexity is captured on our own fleet, so evidence.fanOut is { "provenance": "none", "queries": [] } — no fan-out is claimed. mentions, shopping, and ads are reserved and currently null.

provenance.model

object

Which model produced the answer: { providerId, observedLabel, inferred, confidence }.

provenance.surfacePresent

boolean

When false (paired with a surface_absent warning), Perplexity returned nothing for this prompt. The job still completes with an empty answer, and you are not charged.

Need many surfaces or regions at once? Use the async POST /v1/search (multi-surface, or ?mode=async), which returns a parent jobId plus one child per surface × region. See Asynchronous captures.

Output formats

The full Envelope: job, provenance, answer, and evidence.

Search API

The canonical POST /v1/search endpoint and every body field.

Regions

Capture Perplexity from multiple countries and languages.

Synchronous captures

How the sync default and the per-surface alias return results inline.

Endpoints

Account & discovery

Watches

By surface

Enum

Credits per capture

Request

Body fields

Response (trimmed Envelope)

Output formats

Search API

Regions

Synchronous captures

Enum

Credits per capture

​Request

​Body fields

​Response (trimmed Envelope)

​Related

Output formats

Search API

Regions

Synchronous captures

Request

Body fields

Response (trimmed Envelope)

Related