Perplexity API: Agent API, Search API, pricing and live Twitter (X) data

Perplexity's docs describe five APIs on one key. The two most developers need are the Agent API and the Search API.

Agent API. It follows the OpenAI Responses format, so the docs say you can point the OpenAI SDK at https://api.perplexity.ai/v1 and call client.responses.create(). You either name a model (OpenAI, Anthropic, Google, xAI, NVIDIA and Perplexity families are listed) or an effort level (fast, low, medium, high, xhigh, ultra-preview) that bundles a model, search configuration, step limit and tools. The fast effort level currently runs openai/gpt-6-luna with openai/gpt-5.6-luna as fallback, one step and the web_search tool in Fast Search mode, according to the effort page.

Search API. The docs call it one endpoint, POST https://api.perplexity.ai/search, that returns ranked web results as JSON with no generated answer and no token billing. A request can carry up to five queries, max_results from 1 to 20, search_domain_filter with up to 20 domains, a search_recency_filter of hour, day, week, month or year, and date windows. This is the piece to use when your own model writes the answer.

Official SDKs. Python pip install perplexityai (imported as perplexity) and TypeScript npm install @perplexity-ai/perplexity_ai. Both read PERPLEXITY_API_KEY from the environment.

If you searched for "sonar api", this is the part that changed. Perplexity's migration page says: "Sonar Chat Completions support ended on September 27, 2026. Synchronous and streaming requests keep working: they are being reformulated as Agent API requests, rolling out gradually by model. Asynchronous Sonar requests are not reformulated and are no longer supported." It recommends moving existing Sonar usage to the Agent API and using the Agent API for all new projects.

The Sonar model still exists as an Agent API model: perplexity/sonar, listed at $0.25 per million input tokens, $2.50 per million output tokens and $0.0625 per million cached input tokens. The migration page maps the old Sonar tiers to effort levels:

Request shape. Sonar took a messages array and returned choices. The Agent API takes input and returns a typed output array, with a search_results item for sources and a message item for the answer text. Async jobs move to background mode.

What developers on X were saying. In our 2026 search sample for Sonar terms, 47.0% of 200 posts named Sonar explicitly and 57.0% were replies, which reads like support threads rather than announcements. The "sonar api" phrase also catches unrelated SonarQube posts, so treat that sample as noisy.

All figures below are from Perplexity's pricing, Agent API models and Fast Search pages as read for this guide. They change, so check the pricing page before you budget.

Search billing details. The docs say billing is per successful POST /search request, not per query, so a request with five queries counts as one billable unit. Invalid, rate-limited and failed requests are not billed, and extracted text limits do not change the price.

Agent billing details. Tokens at each model's rate plus tool fees. A flex service tier runs at 0.5x the listed token prices and priority at 2x, only for models that list those tiers. The fast effort level is configured with the priority tier, so its token cost is double the listed model rate.

Other tools. people_search and finance_search are $0.005 per call; a sandbox session is $0.03 per 20-minute window plus $0.0025 per search query made inside it. Embeddings run from $0.004 to $0.05 per million tokens depending on the model.

Perplexity sets your tier from cumulative credit purchases over the life of the account, not from your current balance.

Two limits at once. An Agent API request must pass a request limit (QPS per organization, shared across models and keys) and a token limit (TPM and TPH per organization and model). The 429 body tells you which: request_rate_limit_exceeded, token_rate_limit_exceeded or overloaded (upstream capacity, not a rate limit). A 429 carries Retry-After and no x-ratelimit-* headers; successful responses carry x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used and x-ratelimit-reset.

Search API. 50 query units per second with a burst of 50, the same for every tier. A five-query request is billed once but uses five units.

For comparison on the X side. TwitterAPI.io allows 0.2 requests per second before your first payment, 20 once paid, 50 on Scale and 500 on Business, and up to 1,000 on request.

Create a project first. The API key management page says you must create a project in the console (console.perplexity.ai/project/settings) before you can generate keys.

Generate the key. Open the API Keys page of that project and create a key. The docs warn that the full token is shown only once and cannot be retrieved later, so store it immediately in a secret manager or an environment variable named PERPLEXITY_API_KEY.

Manage keys in code. After the first key exists you can create and revoke more with the /generate_auth_token and /revoke_auth_token endpoints. A revoked key cannot be recovered, so roll new keys into your apps before revoking old ones.

Never ship the key to a browser. The docs say to keep keys out of client-side code and public repositories. The same rule applies to your TwitterAPI.io key: call both from your server.

We searched Perplexity's full documentation text for X or Twitter data sources and found none: the built-in tools are web search, image search, URL fetch, people search, finance search, sandbox and MCP. You can add x.com to search_domain_filter, but that only narrows results to pages from that domain that are already in the index; it is not a feed of new posts. We did not call the Search API, so we cannot tell you how many fresh posts that filter returns.

Our X sample shows what you would be trying to catch. Searching X for the exact phrase "perplexity api" (newest first) returned 298 posts covering 574 days, with only 9 in the last 30 days and a median gap of 23.1 hours between posts. That is a thin, bursty stream: a page or two of results covers more than a year, and the newest few posts are the signal that matters.

What people talk about. 22.5% of the posts mention pricing, cost or credits and 9.7% mention errors, limits or outages. Those are exactly the questions ("is it down?", "did the price change?") where a live X search adds something the web index does not have yet. Only 1.3% mention the Agent API by name, which suggests the developer conversation has not caught up with the docs.

The official accounts. @perplexity_ai posted 0.42 times a day over the sample window and @AravSrinivas 3.27 times a day. Posts that mention the API, Sonar, docs or developers were 7.6% and 8.8% of their original posts. Median views for those API posts were 148,403 on @perplexity_ai, close to the 150,346 of their other posts.

The pattern is simple: run the web search and the X search side by side, merge both into one context block, and let a model answer with citations. You can wire the X call in two ways.

Option 1, call both yourself (shown in the code below). Your server calls Perplexity POST /search for web pages and TwitterAPI.io /twitter/tweet/advanced_search for posts, then sends both as context to the Agent API. Predictable cost: one billed request on each side.

Option 2, a custom function in the Agent API. The Agent API's custom functions let the model request a tool you define (for example search_x_posts(query)); the docs say the API never executes it for you, so your code runs the TwitterAPI.io call and returns a function_call_output. The model decides when it needs X data.

The X price, in context. TwitterAPI.io bills $0.15 per 1,000 tweets returned (15 credits per tweet, minimum 15 credits per request, so an empty search costs $0.00015). The official X API pay-per-usage rate card on docs.x.com/x-api/getting-started/pricing lists $0.005 per post read, which is $5 per 1,000 posts, about 33x more. Our search pages averaged 19.9 tweets each.

Speed. In six single-page searches timed end to end through our shared, rate-limited study client (Python start-up and queue waits included), the median was 3.01 seconds and the slowest 3.93 seconds for 20 tweets. Raw API latency is lower; this is the honest upper figure we measured.

Agent API tokens come on top. The table excludes the answer step. Budget it from the model table: a few thousand tokens of context into perplexity/sonar is a fraction of a cent per answer at $0.25 per million input tokens.

Question. How much developer conversation about the Perplexity API happens on X, how fresh it is, what it is about, and what the X side of a paired research agent costs.

Accounts and queries. Timelines of @perplexity_ai (organization) and @AravSrinivas (CEO, public figure), 200 posts each, via /twitter/user/last_tweets. Searches via /twitter/tweet/advanced_search with queryType=Latest: the exact phrase "perplexity api" (298 posts) and Sonar terms (200 posts), retweets excluded. Plus six single-page searches timed end to end.

Window and size. The most recent posts at collection time, collected in 2026: 898 posts from 57 requests, about $0.15 of credits.

What the sample cannot show. Topic shares come from keyword matching on post text, not manual coding. The Sonar query also catches unrelated SonarQube posts. We did not call the Perplexity API, so we cannot say which of these posts its index would return.

Privacy. Aggregates only. Search results come mostly from private individuals: raw pages were kept off the repository, and the published sample holds de-identified rows with no IDs, URLs, text or handles.

Writing to X is a separate product. If your agent should also post the summary, TwitterAPI.io's write endpoints run through an authenticated session: one /twitter/user_login_v2 login ($0.10, with a proxy you supply) returns login_cookies, then each post such as /twitter/create_tweet_v2 is 60 credits ($0.0006). The call acts as that account, so X can rate-limit, lock or suspend it; keep a human pace, expect occasional re-login, and note that billing is per HTTP 200 call. Reads need no X account.

Free start. New TwitterAPI.io accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days). Purchased credits never expire. Plans run from Starter at $29 a month to Business at $1,499; see /pricing for details.

Next step. Create a key in the TwitterAPI.io dashboard, copy the script below, set PERPLEXITY_API_KEY and TWITTERAPI_IO_KEY, and run it against a question your users actually ask. The full parameter list for advanced_search is in the docs at docs.twitterapi.io.