# Perplexity Agent API and Search API for marketers

> When marketers should use the Perplexity Agent API or Search API, what they cost, how filters work, and a starter script for citation checks.

Source: https://mentionx.ai/learn/perplexity/perplexity-api-agent-search-marketers  
Author: Dipuck Jones, founder of MentionX  
Updated: 5 November 2026  
Level: Practitioner

**Perplexity has two APIs that matter to marketers. The Agent API (`POST https://api.perplexity.ai/v1/agent`) returns a written answer with citations, using effort levels from fast to ultra-preview. It replaced the Sonar API, whose support ended on 27 September 2026. The Search API (`POST https://api.perplexity.ai/search`) returns ranked web results with no generated answer, for $5 per 1,000 requests. Use the Agent API to sample answers, and the Search API to see which pages rank for a query.**

> **Key takeaways**
>
> - Agent API: answers plus citations. Choose an `effort` level, and pin a version for tracking stability.
> - Search API: ranked results (title, URL, snippet, date), up to 20 per query and up to 5 queries per request.
> - Filters (domain, recency, country or location, language) make research repeatable.
> - API answers aren't identical to the consumer app, so use them as a consistent sample, not ground truth.

*Checked 5 November 2026 (CET) against the Perplexity Help Center, Perplexity blog, Perplexity API docs and the outlets cited in Sources. Perplexity renames and moves features often, so confirm labels and limits in your own account. "Our view" marks MentionX opinion. Ledgerline is a fictional company used for illustration.*

## Which API do you need?

| Job | API | Why |
|---|---|---|
| "Which brands does Perplexity mention for this buyer question?" | Agent API | You need the written answer and its citations |
| "Which pages rank for this query in Perplexity's index?" | Search API | Ranked results, cheaper and faster |
| Daily news monitoring for competitors | Search API with a recency filter | Results only, easy to diff |
| Research summaries in a workflow | Agent API, `low` or `medium` | Multi-step research with citations |
| Large overnight jobs | Agent API Batch | Lower-priority, bulk processing |

## How does the Agent API work?

You send an `input` and an `effort` level. Perplexity bundles a model, search configuration, tools and a system prompt for each effort level.

| Effort level | Good at (Perplexity's description, paraphrased) |
|---|---|
| fast | Single facts and short summaries with citations |
| low | Everyday research with light multi-step lookups |
| medium | Multi-hop browsing across many sources |
| high | Exhaustive, source-heavy research |
| xhigh | Open-ended agentic work, including code in a sandbox |
| ultra-preview | Broadest coverage, with long runs |

Two settings matter for tracking:

- **Pinning.** `effort="fast"` follows Perplexity's latest configuration. `effort="fast@2026-10-16.0"` (an example version) stays fixed, which keeps month-on-month comparisons fair.
- **`reasoning.effort` is separate.** It controls the model's reasoning, not the effort level.

If you are migrating from Sonar, Perplexity's guide maps sonar and sonar-pro to fast, sonar-reasoning-pro to low, and sonar-deep-research to high. Check the migration page for your exact case.

### Starter script

```python
# pip install perplexityai ; set PERPLEXITY_API_KEY in your environment
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    effort="fast",
    input="What are the best accounts payable automation tools for mid-market companies?",
)

print(response.output_text)
```

The response also includes the sources used. Log both the text and the cited URLs for each prompt.

## What does the Agent API cost?

You pay for model tokens plus tool calls. Published tool prices (Nov 2026):

| Tool | Price |
|---|---|
| web_search | $2.50 per 1,000 calls, or $1.00 per 1,000 with `search_type: "fast"` |
| fetch_url | $0.0005 per call |
| People or finance search | $0.005 per call |
| Code sandbox | $0.03 per session (check the docs for the unit) |

The fast to xhigh effort levels default to fast search. Check the pricing page before budgeting, because model token prices vary by underlying model.

## How do web_search filters work?

Inside the `web_search` tool you can add:

| Filter | What it does |
|---|---|
| `search_domain_filter` | Include up to 20 domains, or exclude them with a `-` prefix. Use one mode, not both |
| `search_recency_filter` | hour, day, week, month or year |
| `user_location` | Country, region, city and coordinates |
| Token budgets | `max_tokens` and `max_tokens_per_page` to limit search context |

```python
response = client.responses.create(
    effort="low",
    input="What changed in Competitor A's pricing this month?",
    tools=[{
        "type": "web_search",
        "filters": {
            "search_domain_filter": ["competitor-a.example"],
            "search_recency_filter": "month"
        }
    }],
)
```

> **Pro move:** for share-of-citation tracking, run the same prompt with no domain filter (what the engine picks) and with an exclude filter on your own domain (who wins when you're absent). The gap shows which third parties you need ([lesson 16](https://mentionx.ai/learn/perplexity/perplexity-citation-gap-earned-media)).

## How does the Search API work?

```python
from perplexity import Perplexity

client = Perplexity()

search = client.search.create(
    query=["accounts payable automation software", "duplicate invoice detection"],
    max_results=10,
    country="US",
)

for result in search.results:
    print(result.title, result.url)
```

Key facts:

- **Price:** $5 per 1,000 requests. A request with several queries (up to five) is billed as one request but counts once per query against rate limits.
- **Results:** 1-20 per query (default 10), with title, URL, snippet and date.
- **Filters:** domain, recency or date range, country and language.
- **Architecture:** Perplexity says the index covers more than 200 billion URLs and ranks sub-document spans, not just whole pages ([lesson 13](https://mentionx.ai/learn/perplexity/perplexity-how-sources-are-chosen)).

## What else is in the platform?

- **Batch API** for bulk Agent requests.
- **Background mode** for long-running requests.
- **MCP server** to use Perplexity search from tools such as Claude or Cursor.
- **Cookbook** examples, including news monitors and domain filtering patterns.

## How do you keep API work safe and cheap?

- **Store keys in a secret manager or environment variable.** Never paste them into sheets, docs or prompts.
- **Set spend alerts** in the API console.
- **Log everything:** prompt, effort level and version, date, answer, citations and cost.
- **Respect rate limits.** Back off on 429 errors.
- **Sample, don't scrape.** A focused prompt set run weekly beats thousands of random queries.

## Worked example: Ledgerline

*Ledgerline is a fictional accounts-payable software company. Details are illustrative.*

Ledgerline's analyst set up a weekly job for 40 buyer prompts.

| Component | Choice |
|---|---|
| Answer sampling | Agent API, fast effort pinned to one version, 40 prompts weekly |
| Ranking check | Search API, the same 40 queries, US, top 10 |
| Logging | One row per prompt per week: answer, cited URLs, brands mentioned, cost |
| Cost | A few dollars a month at this volume (check against your own token usage) |
| Review | Monthly, in the AI visibility report ([lesson 19](https://mentionx.ai/learn/perplexity/perplexity-share-of-citations-tracking)) |

### Walkthrough

1. Created an API key and stored it in the team's secret manager.
2. Ran the starter script for 5 prompts to check output and cost.
3. Pinned the effort version for comparability.
4. Added the Search API run for the same queries.
5. Wrote results to a sheet, then later moved the job to n8n.
6. Recorded the version change whenever they re-pinned.

## Common mistakes

- **Treating API answers as what every user sees.** They're a sample.
- **Not pinning.** Silent configuration changes break trends.
- **Mixing include and exclude in the domain filter.** Use one mode.
- **Keys in spreadsheets.** Use a secret store.

## Try it yourself

Install the SDK, run the starter script for three of your buyer prompts, and log brands mentioned and cited URLs. Then run the same three as Search API queries. Compare which of your pages appear in each.

## Quick quiz

**1. What replaced the Sonar API?**

*Answer:* The Agent API, with effort levels.

**2. What does the Search API return?**

*Answer:* Ranked results with title, URL, snippet and date, but no generated answer.

**3. Why pin an effort version?**

*Answer:* To keep tracking comparable over time.

## What should you check before the next lesson?

- The API key is stored safely and spend alerts are set.
- A five-prompt test is logged with answers, citations and cost.
- You've decided on dynamic or pinned effort.

Previous: [The Comet browser](https://mentionx.ai/learn/perplexity/perplexity-comet-browser-marketers). Next: [Automate Perplexity research with n8n](https://mentionx.ai/learn/perplexity/perplexity-n8n-automation). Or return to the [Perplexity for Marketers track](https://mentionx.ai/learn/perplexity/perplexity-for-marketers). Related: [Share of citations tracking](https://mentionx.ai/learn/perplexity/perplexity-share-of-citations-tracking), [Build your own AI visibility tracker with APIs](https://mentionx.ai/learn/tools/build-own-ai-visibility-tracker-apis).

## Common questions

**What happened to the Sonar API?** Perplexity ended Sonar support on 27 September 2026 and moved developers to the Agent API, which uses effort levels such as fast, low and high instead of Sonar model names.

**Does the API give the same answer as perplexity.ai?** Not exactly. The API and the consumer app use different configurations, so treat API results as a consistent sample rather than a copy of what a given user sees.

**Do I need a developer?** For a first test, no. The quickstart takes minutes. For a scheduled tracking job, involve someone who can manage keys, logging and costs, or use n8n.

## Sources

- Perplexity API docs, [Agent API quickstart](https://docs.perplexity.ai/docs/agent-api/quickstart)
- Perplexity API docs, [Effort levels](https://docs.perplexity.ai/docs/agent-api/effort)
- Perplexity API docs, [Web search tool](https://docs.perplexity.ai/docs/agent-api/tools/web-search)
- Perplexity API docs, [Migrate from Sonar](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/overview)
- Perplexity API docs, [Search API quickstart](https://docs.perplexity.ai/docs/search/quickstart)
- Perplexity API docs, [Pricing](https://docs.perplexity.ai/docs/getting-started/pricing)
- Perplexity blog, [Architecting and Evaluating an AI-First Search API](https://www.perplexity.ai/hub/blog/architecting-and-evaluating-an-ai-first-search-api)
- All accessed 5 Nov 2026.

## Frequently asked questions

### What happened to the Sonar API?

Perplexity ended Sonar support on 27 September 2026 and moved developers to the Agent API, which uses effort levels such as fast, low and high instead of Sonar model names.

### Does the API give the same answer as perplexity.ai?

Not exactly. The API and the consumer app use different configurations, so treat API results as a consistent sample rather than a copy of what a given user sees.

### Do I need a developer?

For a first test, no. The quickstart takes minutes. For a scheduled tracking job, involve someone who can manage keys, logging and costs, or use n8n.

---

Written and reviewed by Dipuck Jones for MentionX Learn. The HTML version of this page: https://mentionx.ai/learn/perplexity/perplexity-api-agent-search-marketers