Wide Research - Perplexity

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 (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.

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)

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);
}

# 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:

Submit in the background

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.

Poll until it finishes

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.

Download the results

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.

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

Background mode

Submit, poll, stream, and reconnect long-running runs.

Working with files

List and download the files a run produces.

Presets

See every preset and what it configures.

WANDR Benchmark

Read the research behind wide-and-deep evaluation.

​Overview

​Quickstart

​How it works

​Next Steps

Background mode

Working with files

Presets

WANDR Benchmark

Overview

Quickstart

How it works

Next Steps