# Perplexity (/docs/perplexity)

Web-grounded research via Perplexity Sonar. Natural-language questions, real source citations

Ask a natural-language question and get a synthesised answer plus the URLs Sonar cited as evidence. 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 a structured social-media call cannot give you.

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

## Quickstart

### 1. Run a research query

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

### 2. Read the answer and its sources

```json title="Response"
{
  "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
}
```

## Ask a question

| Endpoint                      | Credits | What it returns                                                       | Key parameters |
| ----------------------------- | ------- | --------------------------------------------------------------------- | -------------- |
| `GET /v1/perplexity/research` | 1       | One synthesised answer plus the URL citations Sonar used to ground it | `query`        |

Both response 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. |

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

## Which grounded-research endpoint to use

Four endpoints answer questions off the open web. They differ in what you get back rather than in what they can reach.

| Endpoint                      | Credits          | Reach for it when                                                                                                                                                                             |
| ----------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/perplexity/research` | 1                | You want a question in words and an answer in words. The cheapest of the four.                                                                                                                |
| `GET /v1/tavily/search`       | 1                | You want the sources themselves, filterable by domain, date and topic, with an optional written answer.                                                                                       |
| `GET /v1/web/search`          | 2 per 10 results | You want web, news and image results in the unified `WebPageList` shape, optionally scraped inline.                                                                                           |
| `GET /v1/prism/answers`       | 15               | One answer is not enough to act on. Sends the same question to Perplexity, Grok and Tavily, keeps each answer verbatim, merges citations, and adds a matrix of where they agree and disagree. |

## All endpoints

## Platform notes

- **Refunded automatically on upstream failure** (502 `UPSTREAM_ERROR`). You are never out of pocket on a transient blip.
- **Computed-fields enrichment does not apply.** This endpoint returns research output, not social content, so `engagement_rate`, `language` and the rest are not attached.
- Authentication is your SocialCrawl `x-api-key`. You do not need a Perplexity account.
- Responses follow the unified SocialCrawl envelope (`success`, `data`, `credits_used`, `credits_remaining`, `request_id`, `cached`).

## Next steps

- [Tavily](/docs/tavily.md): Ranked, filterable web results plus extract, map, and crawl.
- [Prism](/docs/prism.md): Multi-engine consensus and the rest of the composite catalogue.
- [Web scraping](/docs/web.md): Search, scrape, map, extract, crawl, and monitor any public page.