> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Wide Research
> Run wide-and-deep research tasks with the wide-research preset — build large, evidence-backed collections in the background.
## Overview
`wide-research` is the preset for building large, evidence-backed collections. Point it at a task like "find every company that matches X and cite a source for each" and it discovers the qualifying entities and gathers supporting evidence for each one, then writes the results to a file you download.
This is the task shape measured by Perplexity's [WANDR benchmark](https://research.perplexity.ai/articles/wandr-benchmark-evaluating-research-agents-that-must-search-wide-and-deep) (Wide ANd Deep Research): discover a broad set of items (wide) and investigate each far enough to back every claim with a source (deep). It's a class of research the Agent API is built for — Perplexity's search-orchestration system leads the WANDR benchmark, and `wide-research` puts that same configuration behind a single preset.
## Quickstart
Wide research runs take minutes, so submit them with `background=true`, poll the response by id until it finishes, then download the file the agent produced.
```python Python theme={null}
import time
from perplexity import Perplexity
client = Perplexity()
# 1. Submit in the background
response = client.responses.create(
preset="wide-research",
background=True,
input=(
"Find at least 70 US-based companies with a CEO or CFO appointment first "
"announced between March 1 and April 30, 2026. For each, cite an authoritative "
"page that names the company and appointee and gives the role and date. Write "
"the results to results.jsonl, one JSON record per line with fields: "
"company, appointee, role, announcement_date, url."
),
)
# 2. Poll until the run reaches a terminal status
while response.status not in ("completed", "failed", "cancelled"):
time.sleep(5)
response = client.responses.retrieve(response.id)
# 3. Download every file the run produced
for file in client.responses.files.list(response.id).data:
client.responses.files.content(
file_id=file.id, response_id=response.id
).write_to_file(file.filename)
```
```typescript Typescript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity();
// 1. Submit in the background
let response = await client.responses.create({
preset: 'wide-research',
background: true,
input:
'Find at least 70 US-based companies with a CEO or CFO appointment first ' +
'announced between March 1 and April 30, 2026. For each, cite an authoritative ' +
'page that names the company and appointee and gives the role and date. Write ' +
'the results to results.jsonl, one JSON record per line with fields: ' +
'company, appointee, role, announcement_date, url.',
});
// 2. Poll until the run reaches a terminal status
while (!['completed', 'failed', 'cancelled'].includes(response.status)) {
await new Promise((r) => setTimeout(r, 5000));
response = await client.responses.retrieve(response.id);
}
// 3. List the files the run produced, then download each by id
const files = await client.responses.files.list(response.id);
for (const file of files.data) {
console.log(file.id, file.filename, file.bytes);
}
```
```bash cURL theme={null}
# 1. Submit in the background — capture the response id
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"preset": "wide-research",
"background": true,
"input": "Find at least 70 US-based companies with a CEO or CFO appointment first announced between March 1 and April 30, 2026. For each, cite an authoritative page that names the company and appointee and gives the role and date. Write the results to results.jsonl, one JSON record per line with fields: company, appointee, role, announcement_date, url."
}'
# 2. Poll by id until status is completed, failed, or cancelled
curl https://api.perplexity.ai/v1/responses/$RESPONSE_ID \
-H "Authorization: Bearer $PERPLEXITY_API_KEY"
# 3. List and download the files the run produced
curl https://api.perplexity.ai/v1/responses/$RESPONSE_ID/files \
-H "Authorization: Bearer $PERPLEXITY_API_KEY"
curl https://api.perplexity.ai/v1/responses/$RESPONSE_ID/files/$FILE_ID/content \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-o results.jsonl
```
## How it works
A wide-research run has three parts, each backed by its own feature page:
Set `preset="wide-research"` and `background=true`, and pass the task as `input`. The submit call returns immediately with a response `id` and a `queued` status; the run continues server-side even if your client disconnects. See [Background mode](/docs/agent-api/background-mode).
Retrieve the response by `id` until its `status` is terminal — `completed`, `failed`, or `cancelled`. You can also stream the run live and reconnect after a drop; see [Background mode](/docs/agent-api/background-mode#stream-and-reconnect).
The agent writes the collection to a file in the sandbox and delivers it, so it shows up as a `share_file` item in the response `output`. List and download it by response `id`. See [Working with files](/docs/agent-api/working-with-files).
Wide-research quality tracks how precisely you specify the task. Give it a concrete target ("at least 70 companies"), clear qualification rules (dates, geography, thresholds), a required source per record, and an explicit output shape — name the file and list the exact fields per row. Structured, cited output is easier to verify and consume downstream.
## Next Steps
Submit, poll, stream, and reconnect long-running runs.
List and download the files a run produces.
See every preset and what it configures.
Read the research behind wide-and-deep evaluation.