# Perplexity (/docs/perplexity)



Perplexity [#perplexity]

Web-grounded research via Perplexity Sonar. Ask natural-language questions, get a synthesised answer plus the URLs Sonar cited as evidence.

Base URL: `/v1/perplexity/...`

Perplexity uses the same authentication and credit model as every other SocialCrawl endpoint — pass your `x-api-key` header, pay 1 credit per call, get a unified response envelope. The fact that the upstream is the Vercel AI Gateway → Perplexity Sonar is invisible to you.

Best for freeform questions like "what is the latest funding round for Anthropic?" or "summarise this week's biggest LLM releases" that need fresh, web-grounded answers — the kind of question a structured social-media call cannot answer.

Getting Started [#getting-started]

1\. Run a research query [#1-run-a-research-query]

```bash
curl "https://www.socialcrawl.dev/v1/perplexity/research?query=what+is+the+capital+of+france" \
  -H "x-api-key: sc_your_api_key_here"
```

2\. Read the answer + sources [#2-read-the-answer--sources]

```json
{
  "success": true,
  "platform": "perplexity",
  "endpoint": "/v1/perplexity/research",
  "data": {
    "answer": "Paris is the capital of France.",
    "sources": [
      {
        "url": "https://en.wikipedia.org/wiki/Paris",
        "title": "Paris - Wikipedia"
      }
    ]
  },
  "credits_used": 1,
  "credits_remaining": 99,
  "request_id": "req-a1b2c3d4e5f6",
  "cached": false
}
```

`data.sources` is always an array. Empty arrays are legal — Sonar may answer one-line factual questions without citing.

Endpoints [#endpoints]

<PlatformEndpoints platform="perplexity" />

Which grounded-research endpoint to use [#which-grounded-research-endpoint-to-use]

Four endpoints answer questions off the open web, and they differ in what you get back rather than in what they can reach:

* **`GET /v1/perplexity/research`** (1cr) — one synthesised answer with its citations. The cheapest way to ask a question in words and get an answer in words.
* **`GET /v1/tavily/search`** (1cr) — ranked results you can filter by domain, date, and topic, with an optional written answer alongside them. Reach for it when you want the sources themselves, not just a conclusion.
* **`GET /v1/web/search`** (2cr per 10 results) — web, news, and image results in the unified `WebPageList` shape, with the option to scrape each result inline.
* **`GET /v1/prism/answers`** (15cr) — the same question sent to Perplexity, Grok, and Tavily at once, each answer kept verbatim, citations merged, plus a matrix of where they agree and disagree. Worth the price only when a single answer is not enough to act on.

Response Shape [#response-shape]

Both fields are always present on success:

| Field          | Type                | Notes                                                                               |
| -------------- | ------------------- | ----------------------------------------------------------------------------------- |
| `data.answer`  | string              | Sonar's natural-language reply, grounded in the current web sources it found.       |
| `data.sources` | `{ url, title? }[]` | URL citations Sonar used to ground the answer. Order matches Sonar's emitted order. |

Notes [#notes]

* All endpoints use `GET` method with query parameters
* Authentication via `x-api-key` header
* Responses follow the unified SocialCrawl envelope (`success`, `data`, `credits_used`, `credits_remaining`, `request_id`, `cached`)
* Refunded automatically on upstream failure (502 `UPSTREAM_ERROR`) — you are never out-of-pocket on a transient blip
* Computed-fields enrichment (`engagement_rate`, `language`, etc.) does not apply — this endpoint returns research output, not social content