How to Get Started With the Perplexity Sonar API

The Perplexity Sonar API lets you integrate real-time search capabilities into your own applications, bots, or workflows. Instead of visiting the Perplexity website, you can send a question and receive a cited answer programmatically. This article explains what the Sonar API is, what you need to set it up, and how to make your first API call. You will learn the authentication process, the request format, and how to handle the response.

What the Perplexity Sonar API Does

The Sonar API is a RESTful web service that gives you programmatic access to Perplexity search results. When you send a question, the API runs a live search across the web, compiles an answer, and returns it with citations. This is useful for building custom chatbots, automating research tasks, or adding a search layer to your internal tools.

The API uses the same underlying models as the Perplexity web interface. You can choose between Sonar (the standard model) and Sonar Pro (the higher-capability model with deeper reasoning). Both models support context windows of up to 200,000 tokens, meaning you can include long documents or conversation histories in your requests.

Before you can make calls, you need three things: a Perplexity account, an API key, and a tool to send HTTP requests. The tool can be cURL, Python with the requests library, Postman, or any HTTP client of your choice.

Prerequisites

You must have a Perplexity account with an active subscription that includes API access. As of May 2025, API access is available on the Pro plan and above. Free accounts cannot generate API keys. You also need basic familiarity with HTTP requests and JSON formatting.

Steps to Generate Your API Key and Make Your First Request

Follow these steps to obtain your API key and send a query to the Sonar API. The process is identical for Windows, macOS, and Linux.

1. Log in to your Perplexity account
   Open a browser and go to perplexity.ai. Sign in with the account that has an active Pro subscription.
2. Navigate to API settings
   Click your profile picture or avatar in the top-right corner. Select Settings from the dropdown menu. In the left sidebar, click API.
3. Generate a new API key
   On the API page, click the Generate API Key button. A key string will appear. Copy it immediately and store it in a secure location. Perplexity does not show the full key again after you leave the page.
4. Open your HTTP client
   Open a terminal window for cURL or your preferred API testing tool. This example uses cURL because it is available on all platforms.
5. Construct the POST request
   Paste the following command into your terminal. Replace YOUR_API_KEY with the key you copied. Replace the query text with your own question.

   curl --request POST \
--url https://api.perplexity.ai/chat/completions \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "sonar",
"messages": [
{
"role": "user",
"content": "What is the current population of Tokyo?"
}
]
}'

6. Send the request and review the response
   Press Enter. The API returns a JSON object. The answer text appears in the choices[0].message.content field. The citations array contains URLs to the sources used.

Using Sonar Pro Instead of Sonar

To use the higher-capability model, change the model field from "sonar" to "sonar-pro". Sonar Pro supports more complex reasoning, longer context, and returns more detailed citations. The request structure is otherwise identical.

Adding System Instructions

You can guide the API behavior by including a system message before the user message. Add an object to the messages array with "role": "system". For example:

{
"role": "system",
"content": "You are a research assistant. Answer concisely and always cite the most recent source."
}

Common Mistakes and How to Avoid Them

New users often encounter a few recurring issues. Knowing these will save time during setup.

401 Unauthorized Error

This error means your API key is missing, expired, or invalid. Verify that the key is correctly copied into the Authorization header. Ensure the key is from the account with an active Pro subscription. If the key was generated on an older plan that no longer supports API access, generate a new key after upgrading.

400 Bad Request – Invalid Model Name

The model name must be exactly sonar or sonar-pro. Typos like sonar-pro with a space or Sonar with a capital S cause a 400 error. Check the JSON payload for exact casing.

Rate Limits Exceeded

Perplexity imposes rate limits based on your subscription tier. If you receive a 429 Too Many Requests response, reduce the frequency of your calls. The Pro plan typically allows 10 requests per minute. Check the API documentation for the latest limits.

Empty or Incomplete Citations

Some queries return answers with few or no citations. This happens when the model relies on internal knowledge for very common facts. To force a search, include the search_domain_filter parameter in the request body. For example:

"search_domain_filter": ["perplexity.ai"]

Item	Sonar	Sonar Pro
Model name	sonar	sonar-pro
Context window	Up to 200,000 tokens	Up to 200,000 tokens
Citation detail	Standard URLs	URLs with inline snippets
Ideal use case	Quick factual queries	Complex research tasks
Cost per request	Lower	Higher

Now you can send queries to the Perplexity Sonar API from any application that supports HTTP requests. Start with a simple cURL command to verify your setup, then move to integrating the API into your own code. For advanced use, explore parameters like temperature for response creativity and max_tokens to limit answer length. The API documentation on the Perplexity website lists all available parameters.