Perplexity Agent API and Search API for marketers

#01Which API do you need?

#02How 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.

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

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

#03What does the Agent API cost?

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

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

#04How do web_search filters work?

Inside the web_search tool you can add:

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"
        }
    }],
)

#05How does the Search API work?

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

#06What 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.

#07How 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.

#08Worked 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.

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.

#09Common 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.

#10Try 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.

#11Quick 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.

#12What 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. Next: Automate Perplexity research with n8n. Or return to the Perplexity for Marketers track. Related: Share of citations tracking, Build your own AI visibility tracker with APIs.

#13Common 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.