---
name: perplexity
description: Use when building AI agents that need web-grounded answers with
  citations, accessing multiple LLM providers through one API, performing
  real-time web search, generating embeddings, making classification decisions,
  or orchestrating complex multi-step research workflows. Agents should reach
  for this skill when users need current information, structured outputs, tool
  integration, or multi-provider model access.
metadata:
  mintlify-proj: perplexity
  version: "1.0"
---

# Perplexity API Platform

## Product summary

Perplexity API Platform is a unified interface for building AI agents with web search, multi-provider LLM access, and structured reasoning. The platform includes five APIs: **Agent API** (web-grounded answers with built-in tools and third-party models), **Search API** (ranked web results as JSON), **Embeddings API** (text vectors for semantic search), **Decisions API** (calibrated probabilities for classification), and **Orchestrator API** (direct model access via OpenAI/Anthropic formats). All APIs share one API key (`PERPLEXITY_API_KEY`) and one host (`api.perplexity.ai`). The Agent API endpoint is `POST /v1/agent` (or `/v1/responses` for OpenAI compatibility). Install the SDK: `pip install perplexityai` (Python) or `npm install @perplexity-ai/perplexity_ai` (TypeScript). See [Agent API quickstart](/docs/agent-api/quickstart) for getting started.

## When to use

Reach for this skill when:

- **Building agents that answer questions with current information**: Use Agent API with `effort` levels or `web_search` tool to ground answers in real-time web data with inline citations.
- **Accessing multiple LLM providers through one API**: Use Agent API to call OpenAI (GPT-6, GPT-5.6), Anthropic (Claude), Google (Gemini), xAI (Grok), and others without managing separate API keys.
- **Needing raw web search results for your own processing**: Use Search API to get ranked results with extracted text, then pass to your model or agent.
- **Extracting structured data from unstructured content**: Use Agent API with `response_format` (JSON Schema) to enforce consistent output formats.
- **Running long-running research or batch processing**: Use Batch API to submit many requests asynchronously (up to 50,000 lines per file).
- **Generating embeddings for semantic search or RAG**: Use Embeddings API with standard or contextualized embeddings.
- **Making yes/no or classification decisions with probabilities**: Use Decisions API for grounded, calibrated answers.
- **Integrating custom tools or external services**: Use Agent API with custom functions, MCP servers, or connectors.

## Quick reference

### Essential endpoints and SDKs

| Task | Endpoint | SDK method |
|------|----------|-----------|
| Ask a question with web search | `POST /v1/agent` | `client.responses.create()` |
| Get raw web results | `POST /search` | `client.search.create()` |
| Generate embeddings | `POST /v1/embeddings` | `client.embeddings.create()` |
| Make a classification decision | `POST /v1/decisions` | `client.decisions.create()` |
| Run batch requests | `POST /v1/batches` | `client.batches.create()` |

### Effort levels (pre-configured Agent API setups)

| Effort | Use when | Max steps | Model |
|--------|----------|-----------|-------|
| `fast` | Single-fact lookups, quick summaries | 1 | GPT-6-Luna |
| `low` | Everyday research, light multi-step | 3 | GPT-5.6-Sol |
| `medium` | Multi-hop browsing, wide aggregation | 5 | GPT-5.6-Sol |
| `high` | Expert-level reasoning, exhaustive sources | 8 | GPT-5.6-Sol |
| `xhigh` | Open-ended agentic work, code execution | 12 | GPT-5.6-Sol |
| `ultra-preview` | Broad research, maximum coverage | 15+ | GPT-5.6-Sol |

### Built-in tools for Agent API

| Tool | Type | Use for |
|------|------|---------|
| Web Search | `web_search` | Real-time web results with domain/date/location filters |
| Fetch URL | `fetch_url` | Extract content from specific URLs |
| Sandbox | `sandbox` | Run Python code in isolated container |
| People Search | `people_search` | Find professionals and people |
| Finance Search | `finance_search` | Retrieve financial data and SEC filings |

### Authentication and configuration

```bash
# Set API key (required for all APIs)
export PERPLEXITY_API_KEY="your_key_here"

# Verify key is set (do NOT print it)
test -n "$PERPLEXITY_API_KEY" && echo "Key is set"
```

### Common request patterns

**Basic Agent API call with effort level:**
```python
response = client.responses.create(
    effort="low",
    input="Your question here"
)
print(response.output_text)
```

**Agent API with specific model:**
```python
response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Your question",
    max_output_tokens=2048
)
```

**Agent API with custom tools:**
```python
response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Your question",
    tools=[
        {"type": "web_search"},
        {
            "type": "function",
            "name": "get_data",
            "description": "Fetch data from your system",
            "parameters": {"type": "object", "properties": {...}}
        }
    ]
)
```

**Search API for raw results:**
```python
search = client.search.create(
    query="your search query",
    max_results=10
)
for result in search.results:
    print(f"{result.title}: {result.url}")
```

**Structured output (JSON Schema):**
```python
response = client.responses.create(
    effort="low",
    input="Extract company info",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "company_info",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "founded": {"type": "integer"}
                },
                "required": ["name", "founded"]
            }
        }
    }
)
```

## Decision guidance

### When to use Agent API vs Search API

| Need | Use Agent API | Use Search API |
|------|---------------|----------------|
| Generated answer with citations | ✓ | — |
| Raw ranked results only | — | ✓ |
| Model reasoning and synthesis | ✓ | — |
| Just web results for your model | — | ✓ |
| Tool integration (sandbox, custom functions) | ✓ | — |
| Lowest cost per request | — | ✓ |

### When to use effort level vs direct model selection

| Scenario | Use effort level | Use direct model |
|----------|-----------------|-----------------|
| Want Perplexity's optimized defaults | ✓ | — |
| Need specific model capability | — | ✓ |
| Want automatic improvements over time | ✓ | — |
| Need exact reproducibility | — | ✓ |
| Unsure which model to pick | ✓ | — |

### When to use streaming vs background mode

| Scenario | Use streaming | Use background |
|----------|---------------|-----------------|
| Real-time user experience | ✓ | — |
| Long-running research (minutes) | — | ✓ |
| Need to keep connection open | ✓ | — |
| Can poll for results later | — | ✓ |
| Batch processing | — | ✓ |

## Workflow

### Typical Agent API workflow

1. **Understand the task**: Determine if you need a generated answer (Agent API), raw results (Search API), embeddings, or a classification decision.

2. **Choose your approach**:
   - For quick answers: Use an effort level (`effort="low"`)
   - For specific model: Use `model="provider/model-name"`
   - For custom tools: Add `tools` array with built-in or custom tools

3. **Build the request**:
   - Set `input` (the question or prompt)
   - Add `instructions` if you need specific behavior
   - Include `tools` if needed (web_search, fetch_url, sandbox, custom functions)
   - Set `max_output_tokens` if you need a limit
   - Add `response_format` if you need JSON Schema output

4. **Handle the response**:
   - Check `response.status` (should be "completed")
   - Extract text from `response.output_text` (SDK convenience property)
   - Iterate `response.output` array for tool results, citations, or generated files
   - Check `response.usage` for token counts and costs

5. **Continue conversation** (if needed):
   - Pass `previous_response_id` to continue context
   - Or replay the full conversation in `input` array with prior messages and tool calls

### Batch processing workflow

1. Create a JSONL file (one JSON request per line, up to 50,000 lines)
2. Upload with `client.files.create(file, purpose="batch")`
3. Create batch with `client.batches.create(file_id)`
4. Poll with `client.batches.retrieve(batch_id)` until status is "completed"
5. Download results with `client.files.content(output_file_id)`

### Custom function workflow

1. Define the function schema in `tools` array with `type: "function"`
2. Call `client.responses.create()` with the tools
3. Check response for `function_call` items in `output` array
4. Execute the function on your side
5. Send followup request with original input + function_call + function_call_output
6. Continue until response status is "completed"

## Common gotchas

- **API key in logs**: Never print, echo, or log your API key. Store in environment variables only. Commands like `echo $PERPLEXITY_API_KEY` leave the key in shell history.

- **Anthropic models require `max_output_tokens`**: Requests using `anthropic/*` models must include `max_output_tokens` or they return HTTP 400. Other models don't require it.

- **Web search is opt-in**: A request with only `model` and `input` answers from the model's knowledge, not the web. Add `effort` level or `tools: [{"type": "web_search"}]` to enable web search.

- **Function calls don't execute server-side**: When the model calls a custom function, the API pauses and returns a `function_call` item. Your code must execute it and send the result back in a followup request.

- **Effort level updates are automatic**: Dynamic effort levels (e.g., `effort="low"`) pick up improvements automatically. Pin a version (e.g., `effort="low@2026-10-16.0"`) if you need stability.

- **Streaming keeps connection open**: Streaming holds the connection for the entire run. For long-running tasks (minutes), use `background=true` instead and poll by ID.

- **Search results may have empty snippets**: Always check if `snippet` is empty or null before passing to your model. Skip those results or fetch the full URL with `fetch_url`.

- **Batch API has 30-day retention**: Files and batch results expire after 30 days. Download outputs before they expire.

- **Tool results are in the output array**: Built-in tools (web_search, sandbox, etc.) return results as separate items in `response.output`, not in the message text. Iterate the array to find `search_results`, `sandbox_results`, etc.

- **JSON Schema first request has delay**: The first request with a new JSON Schema may take 10-30 seconds to prepare. Subsequent requests are fast.

- **Effort level tools merge, not replace**: When you override `tools` under an effort level, they merge per tool type. Listing one tool overrides only that tool's options.

## Verification checklist

Before submitting work:

- [ ] API key is set in environment (`PERPLEXITY_API_KEY`) and not hardcoded
- [ ] Request includes required fields: `input` (or `query` for Search API), and either `effort`, `model`, or `response_format`
- [ ] Anthropic models include `max_output_tokens`
- [ ] Web search is explicitly enabled if current information is needed
- [ ] Custom functions are defined with complete JSON Schema
- [ ] Response status is checked (should be "completed" or "success")
- [ ] Tool results are extracted from `response.output` array, not just message text
- [ ] Streaming or background mode is used appropriately for task duration
- [ ] Batch files are valid JSONL (one JSON object per line)
- [ ] Citations are extracted from search results if needed
- [ ] Token usage and costs are logged from `response.usage`

## Resources

- **Comprehensive navigation**: See [llms.txt](https://docs.perplexity.ai/llms.txt) for a complete page-by-page listing of all documentation.
- **Agent API quickstart**: [https://docs.perplexity.ai/docs/agent-api/quickstart](https://docs.perplexity.ai/docs/agent-api/quickstart) — Start here for web-grounded answers with tools.
- **Effort levels guide**: [https://docs.perplexity.ai/docs/agent-api/effort](https://docs.perplexity.ai/docs/agent-api/effort) — Understand pre-configured setups and when to use each.
- **Search API quickstart**: [https://docs.perplexity.ai/docs/search/quickstart](https://docs.perplexity.ai/docs/search/quickstart) — Get raw ranked web results for your own processing.

---

> For additional documentation and navigation, see: https://docs.perplexity.ai/llms.txt