Perplexity API tutorial: keys, first request, pricing, limits

What the API is

The Perplexity API lets your own code get web-grounded answers. It has its own console, billing and prepaid credits, separate from a Pro or Max subscription. Perplexity's docs list several APIs:

Step 1: Get a key

Sign in to the API console, open your project's API keys page and create a key. Save it in an environment variable, not in your code.

export PERPLEXITY_API_KEY="pplx-..."   # never commit this

Add credits on the Billing page. You can turn on auto top-up, but set a limit you're comfortable with. If you run out of credits, requests fail with HTTP 402.

Step 2: First request (Agent API)

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"effort":"low","input":"List three official sources on US passport renewal times."}'

The effort setting can be fast, low, medium, high or xhigh. Higher effort does more work and costs more, so start low.

Step 3: Tool fees

The Agent API charges for the tools it uses, on top of tokens (docs):

You can restrict web search to certain domains with a domain filter. It's cheaper and gives cleaner answers.

Step 4: Search API (raw results)

If you want ranked links rather than a written answer, use the Search API: $5 per 1,000 requests, or $1 per 1,000 for Fast Search. Check the Search quickstart in the docs for the current request format.

Step 5: Rate limits and tiers

Your tier rises with how much you've bought in total (docs):

If you hit HTTP 429, retry with exponential backoff.

Step 6: Privacy and gotchas

• The docs say API customer content isn't used for training. Zero data retention isn't on by default, so ask Perplexity if you need it.
• There's no fine-tuning.
• API answers can differ from the app's, so test with your own questions.
• Put a monthly cap on auto top-up.

Cost example

Say you make 2,000 Agent calls a month, and each one runs 1 web search ($0.0025): that's $5.00 in search fees, plus token costs. Check token prices on the docs pricing page before you plan a budget.