# Chat Completions Source: https://docs.perplexity.ai/api-reference/chat-completions post /chat/completions Generates a model's response for the given chat conversation. # Changelog Source: https://docs.perplexity.ai/changelog/changelog You can now upload images to Sonar and use them as part of your multimodal search experience.\ Give it a try by following our image upload guide:\ [https://docs.perplexity.ai/guides/image-guide](https://docs.perplexity.ai/guides/image-guide) Looking to narrow down your search results to specific dates?\ We now support date range filtering, allowing you to retrieve results only from a particular timeframe. Check out the guide:\ [https://docs.perplexity.ai/guides/date-range-filter-guide](https://docs.perplexity.ai/guides/date-range-filter-guide) We’ve fully transitioned to our new pricing model: citation tokens are no longer charged.\ If you were already using the `search_context_size` parameter, you’ve been on this model already. This change makes pricing simpler and cheaper for everyone — with no downside. View the updated pricing:\ [https://docs.perplexity.ai/guides/pricing](https://docs.perplexity.ai/guides/pricing) We’ve removed all feature gating based on tiered spending. These were previously only available to users of Tier 3 and above. That means **every user now has access to all API capabilities**, regardless of usage volume or spend. Rate limits are still applicable. Whether you're just getting started or scaling up, you get the full power of Sonar out of the box. We're excited to announce that structured outputs are now available to all Perplexity API users, regardless of tier level. Based on valuable feedback from our developer community, we've removed the previous Tier 3 requirement for this feature. **What's available now:** * JSON structured outputs are supported across all models * Both JSON and Regex structured outputs are supported for `sonar` and `sonar-reasoning` models **Coming soon:** * Full Regex support for all models This change allows developers to create more reliable and consistent applications from day one. We believe in empowering our community with the tools they need to succeed, and we're committed to continuing to improve accessibility to our advanced features. Thank you for your feedback—it helps us make Perplexity API better for everyone. We're excited to announce significant improvements to our Sonar models that deliver superior performance at lower costs. Our latest benchmark testing confirms that Sonar and Sonar Pro now outperform leading competitors while maintaining more affordable pricing. Key updates include: * **Three new search modes** across most Sonar models: * High: Maximum depth for complex queries * Medium: Balanced approach for moderate complexity * Low: Cost-efficient for straightforward queries (equivalent to current pricing) * **Simplified billing structure**: * Transparent pricing for input/output tokens * No charges for citation tokens in responses (except for Sonar Deep Research) The current billing structure will be supported as the default option for 30 days (until April 18, 2025). During this period, the new search modes will be available as opt-in features. **Important Note:** After April 18, 2025, Sonar Pro and Sonar Reasoning Pro will not return Citation tokens or number of search results in the usage field in the API response. Please note that as of February 22, 2025, several models and model name aliases will no longer be accessible. The following model names will no longer be available via API: `llama-3.1-sonar-small-128k-online` `llama-3.1-sonar-large-128k-online` `llama-3.1-sonar-huge-128k-online` We recommend updating your applications to use our recently released Sonar or Sonar Pro models – you can learn more about them here. Thank you for being a Perplexity API user. We are expanding API offerings with the most efficient and cost-effective search solutions available: **Sonar** and **Sonar Pro**. **Sonar** gives you fast, straightforward answers **Sonar Pro** tackles complex questions that need deeper research and provides more sources Both models offer built-in citations, automated scaling of rate limits, and public access to advanced features like structured outputs and search domain filters. And don't worry, we never train on your data. Your information stays yours. You can learn more about our new APIs here - [http://sonar.perplexity.ai/](http://sonar.perplexity.ai/) We are excited to announce the public availability of citations in the Perplexity API. In addition, we have also increased our default rate limit for the sonar online models to 50 requests/min for all users. Effective immediately, all API users will see citations returned as part of their requests by default. This is not a breaking change. The **return\_citations** parameter will no longer have any effect. If you have any questions or need assistance, feel free to reach out to our team at [api@perplexity.ai](mailto:api@perplexity.ai) We are excited to announce the launch of our latest Perplexity Sonar models: **Online Models** - `llama-3.1-sonar-small-128k-online` `llama-3.1-sonar-large-128k-online` **Chat Models** - `llama-3.1-sonar-small-128k-chat` `llama-3.1-sonar-large-128k-chat` These new additions surpass the performance of the previous iteration. For detailed information on our supported models, please visit our model card documentation. **\[Action Required]** Model Deprecation Notice Please note that several models will no longer be accessible effective 8/12/2024. We recommend updating your applications to use models in the Llama-3.1 family immediately. The following model names will no longer be available via API - `llama-3-sonar-small-32k-online` `llama-3-sonar-large-32k-online` `llama-3-sonar-small-32k-chat` `llama-3-sonar-large-32k-chat` `llama-3-8b-instruct` `llama-3-70b-instruct` `mistral-7b-instruct` `mixtral-8x7b-instruct` We recommend switching to models in the Llama-3.1 family: **Online Models** - `llama-3.1-sonar-small-128k-online` `llama-3.1-sonar-large-128k-online` **Chat Models** - `llama-3.1-sonar-small-128k-chat` `llama-3.1-sonar-large-128k-chat` **Instruct Models** - `llama-3.1-70b-instruct` `llama-3.1-8b-instruct` If you have any questions, please email [support@perplexity.ai](mailto:support@perplexity.ai). Thank you for being a Perplexity API user. Stay curious, Team Perplexity Please note that as of May 14, several models and model name aliases will no longer be accessible. We recommend updating your applications to use models in the Llama-3 family immediately. The following model names will no longer be available via API: `codellama-70b-instruct` `mistral-7b-instruct` `mixtral-8x22b-instruct` `pplx-7b-chat` `pplx-7b-online` `sonar-small-chat` `sonar-small-online` `pplx-70b-chat` `pplx-70b-online` `pplx-8x7b-chat` `pplx-8x7b-online` `sonar-medium-chat` `sonar-medium-online` In lieu of the above, we recommend switching to models from the Llama 3 family: `llama-3-sonar-small-32k-chat` `llama-3-sonar-small-32k-online` `llama-3-sonar-large-32k-chat` `llama-3-sonar-large-32k-online` `llama-3-8b-instruct` `llama-3-70b-instruct` Effective immediately, input and output tokens are now charged with the same price. Previously, output tokens were more expensive than input tokens. Prices have generally gone down as a result. **Announcing Our Newest Model** We are excited to announce the launch of our latest Perplexity models: sonar-small-chat and sonar-medium-chat, along with their search-enhanced versions, sonar-small-online and sonar-medium-online. These new additions surpass our earlier models in cost-efficiency, speed, and performance. For detailed information on our supported models, please visit our model card documentation. **Expanded Context Windows** The context window length for several models has been doubled from 8k to 16k, including mixtral-8x7b-instruct and all Perplexity models. 4k tokens are reserved for search results in online models. **Model Deprecation Notice** Please note that as of March 15, the pplx-70b-chat, pplx-70b-online, llama-2-70b-chat, and codellama-34b-instruct models will no longer be available through the Perplexity API. We will gradually phase out less frequently used models in favor of our newer and more performant offerings. **Revised Pricing Structure for 8x7b Models** The pricing for the mixtral-8x7b-instruct model will be adjusted. Previously charged at $0.14 / $0.58 per million input and output tokens, the rates will change to $0.60 / $1.80 per million input and output tokens moving forward. **Increased Public Rate Limits** Public limits for all models have increased by \~2x. Find the current rate limits here. **Access to Citations and Elevated Rate Limits** Responding to popular demand in our API discussion forum, we are introducing URL citation access for our Online LLMs to approved users. For access to citations, or to request a rate limit increase, please complete this form. **Terms of Service and Data Processing Addendum** We wish to reiterate our commitment to data privacy for commercial application developers using the Perplexity API. The updated Terms of Service and Data Processing Addendum can be found here. Thank you for being a Perplexity API user. We're excited to announce that pplx-api is now serving the latest open-source mixture-of-experts model, `mixtral-8x7b-instruct`, at the blazingly fast speed of inference you are accustomed to. We're excited to share two new PPLX models: pplx-7b-online and pplx-70b-online. These first-of-a-kind models are integrated with our in-house search technology for factual grounding. Read our blog post for more information! [https://blog.perplexity.ai/blog/introducing-pplx-online-llms](https://blog.perplexity.ai/blog/introducing-pplx-online-llms) We're also announcing general availability for our API. We've rolled out usage-based pricing, which enables us to gradually relax the rate limits on our models. Follow the updated steps for getting started. We have removed support for `replit-code-v1.5-3b` and `openhermes-2-mistral-7b`. There are no immediate plans to add these models back. If you were a user who enjoyed `openhermes-2-mistral-7b`, try instead using our in-house models, `pplx-7b-chat`, `pplx-70b-chat`! The Perplexity AI API is currently in beta release v0. Clients are not protected from backwards incompatible changes and cannot specify their desired API version. Examples of backwards incompatible changes include... Removing support for a given model. Renaming a response field. Removing a response field. Adding a required request parameter. Backwards incompatible changes will be documented here. Generally, the API is currently designed to be compatible with OpenAI client libraries. This means that, given the same request body, swapping the API base URL and adding your Perplexity API key will yield a response that can be parsed in the same way as the response OpenAI would yield, except for certain explicitly unsupported body parameters documented in the reference (link to reference). # Community & Support Source: https://docs.perplexity.ai/discussions/discussions Our vibrant developer community is ready to welcome you! Connect, share ideas, and collaborate with fellow developers building with the Perplexity API. * [GitHub Discussions](https://github.com/ppl-ai/api-discussion/discussions) - Technical conversations & showcases * [Discord Community](https://discord.gg/perplexity-ai) - Real-time chat & support * [Follow @PPLXDevs](https://twitter.com/PPLXDevs) - Latest updates & announcements Have questions or need assistance? Our dedicated team is committed to your success. * **Direct Support**: [api@perplexity.ai](mailto:api@perplexity.ai) > * **Response Time**: We aim to respond within 24 hours on business days > * **Office Hours**: Weekly office hours at 6 PM ET with James Liounis, Sonar's Customer Success Lead. You can register [here](https://events.zoom.us/ev/Akzh8Q9GwGtQ8-5yeP1A6B0kQBND1W67rbimE3koC4L_L4ZP65f2~Ag4nJHk6gbPxvgM1f_OCr6BzgyKoKK7hLYpE3HmzJ69MnMG3CvFABoNg6Q). ## Developer Resources Found a bug? Help us improve! Submit detailed bug reports through our [GitHub Issue Tracker](https://github.com/ppl-ai/api-discussion/issues/new/choose). Select the appropriate template to help us resolve your issue faster. Built something amazing with the Perplexity API? We'd love to showcase your work! * Contribute to our [API Cookbook](https://github.com/ppl-ai/api-cookbook) by following the instructions [here](https://github.com/ppl-ai/api-cookbook/blob/main/CONTRIBUTING.md). * Share on X/Twitter with [@PPLXDevs](https://twitter.com/PPLXDevs) * Present at our monthly developer showcase Exceptional projects may be featured in our newsletter, blog, and social media channels. Let us amplify your work to thousands of developers and AI enthusiasts! ## Community Highlights Every month, we feature standout projects from our community. [See current highlights](https://github.com/ppl-ai/api-cookbook/blob/main/README.md) Join Perplexity co-founder & CTO Denis Yarats for an overview of our API on April 24 at 11am PT. Denis will provide an introduction to Perplexity's APIs, share benchmark results, and API use cases. New API users who register will get \$50 in free API credits. Register [here](https://events.zoom.us/ev/AldnHwtVxAaIduuxGDzfji4Sgt60oiFFj0hB6-eI74wz9PjxxE9l~AunhmxJPTSCCVS_EYLAWb2fK13t6nBzjAOSliIKRkiK7vl4pDG5iQpKWbw). Explore tutorials, FAQs, and best practices from our team and community contributors. [Browse resources](https://github.com/ppl-ai/api-discussion/) ## Community Guidelines We're committed to fostering an inclusive, helpful, and respectful community. Please follow these guidelines in all interactions: 1. **Be respectful** - Treat everyone with courtesy and professionalism 2. **Be constructive** - Provide helpful feedback and solutions 3. **Share knowledge** - Help others learn and grow 4. **Stay on topic** - Keep discussions relevant to the Perplexity API 5. **No spam or self-promotion** - Share your work in appropriate channels # Frequently Asked Questions Source: https://docs.perplexity.ai/faq/faq The `sonar-reasoning-pro` model is designed to output a `` section containing reasoning tokens, immediately followed by a valid JSON object. As a result, the `response_format` parameter does not remove these reasoning tokens from the output. We recommend using a custom parser to extract the valid JSON portion. An example implementation can be found [here](https://github.com/ppl-ai/api-discussion/blob/main/utils/extract_json_reasoning_models.py). To file a bug report, please use our GitHub repository and file the bug in [issues](https://github.com/ppl-ai/api-discussion/issues). Once you've submitted your report, we kindly ask that you share the link to the issue with us via email at [api@perplexity.ai](mailto:api@perplexity.ai) so we can track it on our end. We truly appreciate your patience, and we'll get back to you as soon as possible. Due to the current volume of reports, it may take a little time for us to respond—but rest assured, we're on it. Our compute is hosted via Amazon Web Services in North America. By default, the API has zero day retention of user prompt data, which is never used for AI training. The only way for an account to be upgraded to the next usage tier is through all-time credit purchase. Here are the spending criteria associated with each tier: | Tier | Credit Purchase (all time) | | ------ | -------------------------- | | Tier 0 | - | | Tier 1 | \$50 | | Tier 2 | \$250 | | Tier 3 | \$500 | | Tier 4 | \$1000 | | Tier 5 | \$5000 | We offer a way to track your billing per API key. You can do this by navigating to the following location: **Settings > View Dashboard > Invoice history > Invoices** Then click on any invoice and each item from the total bill will have a code at the end of it (e.g., pro (743S)). Those 4 characters are the last 4 of your API key. A Feature Request is a suggestion to improve or add new functionality to the Perplexity Sonar API, such as: * Requesting support for a new model or capability (e.g., image processing, fine-tuning options) * Asking for new API parameters (e.g., additional filters, search options) * Suggesting performance improvements (e.g., faster response times, better citation handling) * Enhancing existing API features (e.g., improving streaming reliability, adding new output formats) If your request aligns with these, please submit a feature request here: [Github Feature requests](https://github.com/ppl-ai/api-discussion/issues) 1. The API uses the same search system as the UI with differences in configuration—so their outputs may differ. 2. The underlying AI model might differ between the API and the UI for a given query. 3. We give users the power to tune the API to their respective use cases using sampling parameters like `presence_penalty`, `top_p`, etc. Custom tuning to specific use cases might lead to less generalization compared to the UI. We set optimized defaults and recommend not to explicitly provide sampling parameters in your API requests. We collect the following types of information: **API Usage Data:** We collect billable usage metadata such as the number of requests and tokens. You can view your own usage in the [Perplexity API dashboard](https://perplexity.ai/settings/api). **User Account Information:** When you create an account with us, we collect your name, email address, and other relevant contact information. We do not retain any query data sent through the API and do not train on any of your data. Yes, the [Sonar Models](https://docs.perplexity.ai/guides/model-cards) leverage information from Perplexity's search index and the public internet. You can find our [rate limits here](https://docs.perplexity.ai/guides/usage-tiers). We email users about new developments and also post in the [changelog](/changelog.mdx). 401 error codes indicate that the provided API key is invalid, deleted, or belongs to an account which ran out of credits. You likely need to purchase more credits in the [Perplexity API dashboard](https://perplexity.ai/settings/api). You can avoid this issue by configuring auto-top-up. Currently, we do not support fine-tuning. Please reach out to [api@perplexity.ai](mailto:api@perplexity.ai) or [support@perplexity.ai](mailto:support@perplexity.ai) for other API inquiries. You can also post on our [discussion forum](https://github.com/ppl-ai/api-discussion/discussions) and we will get back to you. We do not guarantee this at the moment. The models are hosted in the US and we do not train on any of your data. And no, your data is not going to China. Yes, our reasoning APIs that use DeepSeek's models are uncensored and on par with the other APIs in terms of content moderation. We expose the CoTs for Sonar Reasoning Pro and Sonar Reasoning. We don't currently expose the CoTs for Deep Research. R1-1776 is an offline chat model that does not search the web. So this model might not have the most up-to-date information beyond its training cutoff date—which should be the same as R1. Reasoning tokens in Deep Research are a bit different than the CoTs in the answer—these tokens are used to reason through the research material before generating the final output via the CoTs. Yes, the API offers exactly the same internet data access as Perplexity's web platform. The Perplexity API is designed to be broadly compatible with OpenAI’s chat completions endpoint. It adopts a similar structure—including fields such as `id`, `model`, and `usage`—and supports analogous parameters like `model`, `messages`, and `stream`. **Key Differences from the standard OpenAI response include:** * **Response Object Structure:** * OpenAI responses typically have an `object` value of `"chat.completion"` and a `created` timestamp, whereas our response uses `object: "response"` and a `created_at` field. * Instead of a `choices` array, our response content is provided under an `output` array that contains detailed message objects. * **Message Details:** * Each message in our output includes a `type` (usually `"message"`), a unique `id`, and a `status`. * The actual text is nested within a `content` array that contains objects with `type`, `text`, and an `annotations` array for additional context. * **Additional Fields:** * Our API response provides extra meta-information (such as `status`, `error`, `incomplete_details`, `instructions`, and `max_output_tokens`) that are not present in standard OpenAI responses. * The `usage` field also differs, offering detailed breakdowns of input and output tokens (including fields like `input_tokens_details` and `output_tokens_details`). These differences are intended to provide enhanced functionality and additional context while maintaining broad compatibility with OpenAI’s API design. # API Roadmap Source: https://docs.perplexity.ai/feature-roadmap Upcoming features and improvements for the Perplexity API designed to enhance your development experience. Our roadmap is shaped by our users - have a feature in mind? Submit your suggestion [here](https://github.com/ppl-ai/api-discussion/issues/new?template=feature_request.md) and help us build the future of AI together. Expanding your ability to access and process information: * Search across various file types * Integration with external data sources * Parity with enterprise connector capabilities This feature will allow your applications to tap into a broader range of data sources for more comprehensive insights. We're expanding our structured outputs capabilities: * **Universal JSON Support**: JSON structured outputs are now available for all models across all tiers * **Complete Regex Support**: Extending regex pattern support to all models (currently available for `sonar` and `sonar-reasoning`) * **Advanced Schema Validation**: Enhanced validation options for more reliable structured data * **Output Templates**: Pre-defined templates for common use cases This expansion will make it easier to build applications that require consistent, structured data from our API responses. We're building a more powerful portal to help you manage your API usage: * **Organization Management**: Create and manage organizations with the ability to invite members with different permission levels * **Enhanced Billing**: Improved tools for managing payment methods and tracking expenses * **Advanced Usage Analytics**: Comprehensive visibility into your usage patterns across multiple API models * **Limits Dashboard**: Clear view of your organization's limits to better plan your resource utilization This revamp will make it easier to manage teams, track usage, and maintain oversight of your API implementation at scale. We're committed to making our documentation a truly exceptional resource: * **Improved Layout**: Optimized structure for better self-serve workflows * **Consistent Design**: Unified branding between our landing page and documentation * **Enhanced Content**: Revised explanations for better developer understanding * **Vertical-Specific Guides**: Specialized documentation for publishers, merchants, and other industry partners * **High-Fidelity Demos**: More comprehensive examples beyond our basic cookbook demos * **Comprehensive Prompt Guide**: In-depth resources to help you build effectively with our search + LLM API * **API Selection Guides**: Clear guidance on which API is best suited for specific scenarios These improvements will help you get up to speed faster and make the most of our API capabilities. We're scaling our infrastructure to support significantly higher request volumes: * Working toward supporting use cases up to 100K RPM * Designed for high-growth startups and enterprise applications This enhancement will ensure our API can grow alongside your application's user base and processing needs. Improving our error framework: * More descriptive error messages * Clearer guidance on resolving common issues This will reduce debugging time and help you understand and address issues more efficiently. More granular control over your search results: * **Localization**: Tune results based on geographic location * **Date Range Filter**: Control the freshness of search results These controls will help you deliver more relevant and targeted results to your users based on their specific context and needs. Broadening the types of content you can work with: * **Image Processing/Search**: Ask questions about images or search using image inputs * **URL Parsing**: Extract and analyze content from web pages These features will enable new use cases and richer interactions within your applications. ## Timeline and Availability This roadmap represents our current development priorities. Features will be released incrementally, with some becoming available in the coming months and others planned for later in the year. We'll announce new feature availability through our [changelog](/changelog) and via email notifications to API users. # API Group Source: https://docs.perplexity.ai/guides/api-organization Learn how to use the Perplexity API Portal to manage access, usage, billing, and team collaboration. This guide walks through how to set up API organizations. If you are new to the API Portal, start by creating an API Group to organize your users and resources. Please refer to the previous guide for this. ## Accessing the API Portal Once signed in, navigate to the left-hand sidebar and expand the **API** section to access your API group and related settings. ![API Group Location](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/api_group_location.png) *** ## Creating and Managing an API Group To set up your organization: 1. Click **API Group** in the left sidebar. 2. Fill out your organization’s name, address, and tax details. Your organization name and address will appear on invoices and help us support you better. ### Fields include: * Organization name and description * Address (Line 1, Line 2, City, State, Zip, Country) * Tax ID ![API Group Details](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/api_group_details.png) *** ## Adding and Managing Members Admins can invite team members to the organization with specific roles: **Admin** or **Member**. ### To Add a Member: 1. Click **+ Add Member**. ![Click on Add Member](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/click_on_add_member.png) 2. Enter the user’s email address and click **Invite**. ![Enter New Member Email](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/enter_new_member_email.png) 3. The invited user will receive an email with a link to join your group. ### Filtering Members by Role Use the dropdown to filter your list of team members by role. ![Filter Members by Role](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/filter_members_by_role.png) ### Roles * **Admin**: Full access to invite/remove members, manage billing, and view usage data. * **Member**: Can view usage and account limits but cannot modify settings. Only Admins can make changes to billing and member permissions. *** ## Billing and Payment Methods Admins can manage billing under the **API Billing** tab. This includes: * Adding or updating credit card information * Enabling or disabling auto-reload * Viewing invoice history and usage tier ![API Billing](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/api_billing.png) * Register your credit card to get started This step will not charge your credit card. It just stores payment information for later API usage. *** ## Viewing Usage Metrics All members can view API usage by selecting **Usage Metrics** from the sidebar. Features include: * Total API call trends over time * Breakdown by API model and key * Optional date range filters Usage metrics help you monitor API activity and optimize for cost or performance. *** ## Viewing Rate Limits and Tiers You can view your API rate limits and organization tier under the **Usage Tier** section in the billing view. Details shown: * Current rate limits per API * Tier level *** ## Managing API Keys The API key is a long-lived access token that can be used until it is manually refreshed or deleted. * Every API call needs a valid API key. You must send the API key as a bearer token in the Authorization header with each API request. Admins can generate and revoke API keys from the **API Keys** tab. ### To create a key: * Click **+ Create Key** to generate a new API key. ![Generate API Keys](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/generate_api_keys.png) API keys are sensitive credentials. Never expose them in client-side code or share them in public repositories. If you run out of credits, your API keys will be blocked until you add to your credit balance. You can avoid this by configuring "Automatic Top Up", which refreshes your balance whenever you drop below \$2. ![Auto Reload](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/auto_reload.png) # Perplexity Crawlers Source: https://docs.perplexity.ai/guides/bots We strive to improve our service every day by delivering the best search experience possible. To achieve this, we collect data using web crawlers (“robots”) and user agents that gather and index information from the internet, operating either automatically or in response to user requests. Webmasters can use the following robots.txt tags to manage how their sites and content interact with Perplexity. Each setting works independently, and it may take up to 24 hours for our systems to reflect changes. | User Agent | Description | | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PerplexityBot | `PerplexityBot` is designed to surface and link websites in search results on Perplexity. It is not used to crawl content for AI foundation models. To ensure your site appears in search results, we recommend allowing `PerplexityBot` in your site’s `robots.txt` file and permitting requests from our published IP ranges listed below.

Full user-agent string: `Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; PerplexityBot/1.0; +https://perplexity.ai/perplexitybot)`

Published IP addresses: [https://www.perplexity.com/perplexitybot.json](https://www.perplexity.com/perplexitybot.json) | | Perplexity‑User | `Perplexity-User` supports user actions within Perplexity. When users ask Perplexity a question, it might visit a web page to help provide an accurate answer and include a link to the page in its response. `Perplexity-User` controls which sites these user requests can access. It is not used for web crawling or to collect content for training AI foundation models.

Full user-agent string: `Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Perplexity-User/1.0; +https://perplexity.ai/perplexity-user)`

Published IP addresses: [https://www.perplexity.com/perplexity-user.json](https://www.perplexity.com/perplexity-user.json)

Since a user requested the fetch, this fetcher generally ignores robots.txt rules. | # Sonar Cookbook Source: https://docs.perplexity.ai/guides/cookbook Guides designed to help developers build with Sonar You can view the cookbook [here](https://github.com/ppl-ai/api-cookbook). # Date Range Filter Guide Source: https://docs.perplexity.ai/guides/date-range-filter-guide The `search_after_date_filter` and `search_before_date_filter` parameters allow you to restrict search results to a specific publication date range. Only results with publication dates falling between these dates will be returned. Dates must be provided in the "%m/%d/%Y" format (e.g., "3/1/2025"). These filters are optional—you may supply either one or both as needed. ## Overview The `search_after_date_filter` and `search_before_date_filter` parameters control which search results are returned by limiting them to a specific publication date range. This feature is useful when you need to: • Narrow down search results to a particular time period • Exclude outdated or overly recent content • Improve relevance by focusing on content published within a defined window To constrain search results by publication date, include the following fields in your request payload: ```bash "search_after_date_filter": "3/1/2025", "search_before_date_filter": "3/5/2025" ``` These filters will be applied in addition to any other search parameters (for example, domain filters). ## Examples **1. Limiting Results to a Specific Date Range** This example limits search results to content published between March 1, 2025, and March 5, 2025. **Request Example** ```bash curl --location 'https://api.perplexity.ai/chat/completions' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "model": "sonar-pro", "messages": [ {"role": "system", "content": "You are an expert on current events."}, {"role": "user", "content": "Show me tech news published this week."} ], "search_after_date_filter": "3/1/2025", "search_before_date_filter": "3/5/2025", "search_recency_filter": "month" }' ``` ```python import requests url = "https://api.perplexity.ai/chat/completions" headers = {"Authorization": "Bearer YOUR_API_KEY"} payload = { "model": "sonar-pro", "messages": [ {"role": "system", "content": "You are an expert on current events."}, {"role": "user", "content": "Show me tech news published this week."} ], "search_after_date_filter": "3/1/2025", "search_before_date_filter": "3/5/2025", "search_recency_filter": "month" } response = requests.post(url, headers=headers, json=payload) print(response.json()) ``` **2. Filtering with a Single Date Parameter** If you only wish to restrict the results to those published on or after a specific date, include just the `search_after_date_filter`: ```bash payload = { "model": "sonar-pro", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Show me news articles published after March 1, 2025."} ], "search_after_date_filter": "3/1/2025", "search_recency_filter": "month" } ``` ## Best Practices **Date Format** • Strict Format: Dates must match the “%m/%d/%Y” format exactly. For example, the date “3/1/2025” or “03/01/2025” is acceptable. • Consistency: Use one or both filters consistently based on your search needs. Combining both provides a clear range. **Client-Side Validation** • Regex Check: Validate date strings on the client side (or via the API) using a regex such as: ```bash date_regex='^(0?[1-9]|1[0-2])/(0?[1-9]|[12][0-9]|3[01])/[0-9]{4}$' ``` ```python date_regex = r'^(0?[1-9]|1[0-2])/(0?[1-9]|[12]\d|3[01])/\d{4}$' ``` This ensures that dates conform to the required format before sending the request. **Performance Considerations** • Narrowing the Search: Applying date range filters typically reduces the number of results, which may improve response times and result relevance. • Avoid Over-Restriction: Ensure that the date range is neither too narrow (limiting useful results) nor too broad (defeating the purpose of the filter). ⸻ # Initial Setup Source: https://docs.perplexity.ai/guides/getting-started Learn how to set up your group, generate API keys, and make your first API call. ## Setting Up Your Group To get started with the Perplexity API: 1. Navigate to your **API Group** [section](https://www.perplexity.ai/account/api/group) of your **Account** [page](https://www.perplexity.ai/account/details). 2. Fill out your group’s name, address, and tax details. ![Organization Setup](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/onboarding_flow/create_new_api_group.png) ## Setting up your billing * Register your credit card to get started ![API Billing](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/api_billing.png) This step will not charge your credit card. It just stores payment information for later API usage. *** ## Generating an API Key Every API call requires a valid API key. To generate one: 1. Go to the **API Keys** tab in the API Portal. 2. Click **+ Create Key** to generate a new API key. The API key is a long-lived access token that can be used until it is manually refreshed or deleted. ![Generate API Key](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/generate_api_keys.png) API keys are sensitive credentials. Never expose them in client-side code or share them in public repositories. *** ## Making Your First API Call * Once you have your API key, you can make your first API call. * Send the API key as a bearer token in the Authorization header with each request. ### Example API Call ```cURL cURL curl --location 'https://api.perplexity.ai/chat/completions' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'Authorization: Bearer {API_KEY}' \ --data '{ "model": "sonar-pro", "messages": [ { "role": "system", "content": "Be precise and concise." }, { "role": "user", "content": "How many stars are there in our galaxy?" } ] }' ``` ```python python from openai import OpenAI YOUR_API_KEY = "INSERT API KEY HERE" messages = [ { "role": "system", "content": ( "You are an artificial intelligence assistant and you need to " "engage in a helpful, detailed, polite conversation with a user." ), }, { "role": "user", "content": ( "How many stars are in the universe?" ), }, ] client = OpenAI(api_key=YOUR_API_KEY, base_url="https://api.perplexity.ai") # chat completion without streaming response = client.chat.completions.create( model="sonar-pro", messages=messages, ) print(response) # chat completion with streaming response_stream = client.chat.completions.create( model="sonar-pro", messages=messages, stream=True, ) for response in response_stream: print(response) ``` If you run out of credits, your API keys will be blocked until you add to your credit balance. You can avoid this by configuring "Automatic Top Up," which refreshes your balance whenever it drops below a certain threshold. ![Auto Reload](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/images/api_portal/auto_reload.png) # Image Guide Source: https://docs.perplexity.ai/guides/image-guide Learn how to use Sonar's image upload feature. The image upload feature allows you to include images in your API requests to support multi-modal conversations alongside text. The API currently only supports images in base64 format with limit of 20 MB per image. Direct file uploads or external URLs are not supported. Supported formats * PNG (image/png) * JPEG (image/jpeg) * GIF (image/gif) Image uploads can be useful for: * Asking questions about visual content (e.g., text in a screenshot, diagram interpretation) * Providing context for follow-up queries * Analyzing visual media as part of a multi-turn conversation ⸻ ## Overview To include an image in a request, you must encode the image as a base64 string and embed it in a data URI using the following format: ```bash data:image/png;base64, ``` Replace image/png with the correct MIME type if you’re using JPEG or GIF: * `image/jpeg` for `.jpg` or `.jpeg` * `image/gif` for .gif This data URI should be included in your API request as part of a messages array, using the `image_url` content type. ⸻ ## Request Format Images must be embedded in the messages array, alongside any text input. Each image should be provided using the following structure: ```bash { "type": "image_url", "image_url": { "url": "data:image/png;base64," } } ``` ⸻ ## Examples ```bash cURL curl --location 'https://api.perplexity.ai/chat/completions' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "sonar-pro", "stream": false, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Can you describe this image?" }, { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." } } ] } ] }' ``` ```python python import requests import base64 # Read and encode image as base64 with open("path/to/your/image.png", "rb") as image_file: base64_image = base64.b64encode(image_file.read()).decode("utf-8") image_data_uri = f"data:image/png;base64,{base64_image}" # API request payload url = "https://api.perplexity.ai/chat/completions" headers = { "Authorization": "Bearer YOUR_API_KEY", "accept": "application/json", "content-type": "application/json" } payload = { "model": "sonar-pro", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "Can you describe this image?"}, {"type": "image_url", "image_url": {"url": image_data_uri}} ] } ], "stream": False } response = requests.post(url, headers=headers, json=payload) print(response.json()) ``` * Image and regex cannot be used together in the same request. * `sonar-deep-research` does not support image input. # Integrating MCP with Perplexity's Sonar API Source: https://docs.perplexity.ai/guides/mcp-server Learn about the MCP server implementation for the Sonar API. ## What is MCP? The **Model Context Protocol (MCP)** is an open standard designed to connect AI assistants with the systems where data lives. By providing a universal interface for AI applications to access structured and unstructured data, MCP eliminates the need for custom integrations, enabling AI models to retrieve real-time, relevant information more efficiently. Learn more about MCP [here](https://modelcontextprotocol.io/introduction). ## MCP Server for Perplexity's Sonar API Our **MCP server implementation** for Sonar allows any AI-powered tool to perform real-time, web-wide research using Perplexity’s powerful search engine. This server acts as a bridge between AI applications and the Sonar, enabling seamless integration for retrieving and synthesizing relevant, up-to-date information from the web. ### How It Works * The **Perplexity Ask MCP Server** follows MCP’s **open standard**, allowing any AI assistant or automation tool to connect to the **Sonar API** for live web searches. * AI models can query the server for information retrieval, leveraging Perplexity’s search capabilities to return the most relevant insights. ### Example: Using MCP with Claude Claude is one example of how this MCP server can be used effectively. When connected to Claude, the **Perplexity Ask MCP Server** enables it to **perform live web searches** and return **highly relevant, up-to-date responses**, enhancing its ability to provide real-time knowledge. ### Where to Find the Documentation Developers looking to integrate and deploy the **Perplexity Ask MCP Server** can find our implementation, detailed documentation, and setup instructions in our official MCP repository: 📖 [**Perplexity Ask MCP Server**](https://github.com/ppl-ai/modelcontextprotocol/tree/main) This includes: * Implementation code * Setup instructions * Configuration steps * API usage guidelines * Deployment and troubleshooting tips # Pricing Source: https://docs.perplexity.ai/guides/pricing ## **Non-Reasoning Models** *Models optimized for fast, cost-effective search and information retrieval.* Advanced search model optimized for complex queries and deeper content understanding.\ [Learn more →](../models/models/sonar-pro) **Pricing:** | Metric | High   | Medium   | Low   | | ------------------------------- | :----: | :------: | :----: | | **Input Tokens (Per Million)** | \$3 | \$3 | \$3 | | **Output Tokens (Per Million)** | \$15 | \$15 | \$15 | | **Price per 1000 Requests** | \$14 | \$10 | \$6 | Lightweight, cost-effective search model designed for quick, grounded answers.\ [Learn more →](../models/models/sonar) **Pricing:** | Metric | High   | Medium   | Low   | | ------------------------------- | :----: | :------: | :----: | | **Input Tokens (Per Million)** | \$1 | \$1 | \$1 | | **Output Tokens (Per Million)** | \$1 | \$1 | \$1 | | **Price per 1000 Requests** | \$12 | \$8 | \$5 | *** ## **Reasoning Models** *Models optimized for multi-step reasoning, problem-solving, and real-time search.* Enhanced reasoning model with multi-step problem-solving capabilities and real-time search.\ [Learn more →](../models/models/sonar-reasoning-pro) **Pricing:** | Metric | High   | Medium   | Low   | | ------------------------------- | :----: | :------: | :----: | | **Input Tokens (Per Million)** | \$2 | \$2 | \$2 | | **Output Tokens (Per Million)** | \$8 | \$8 | \$8 | | **Price per 1000 Requests** | \$14 | \$10 | \$6 | Quick problem-solving and reasoning model, ideal for evaluating complex queries.\ [Learn more →](../models/models/sonar-reasoning) **Pricing:** | Metric | High   | Medium   | Low   | | ------------------------------- | :----: | :------: | :----: | | **Input Tokens (Per Million)** | \$1 | \$1 | \$1 | | **Output Tokens (Per Million)** | \$5 | \$5 | \$5 | | **Price per 1000 Requests** | \$12 | \$8 | \$5 | *** ## **Deep Research Models** *Models designed for exhaustive research, expert-level analysis, and detailed report generation.* Best suited for exhaustive research, generating detailed reports and in-depth insights.\ [Learn more →](../models/models/sonar-deep-research) **Pricing:** | Metric   | Cost   | | ------------------------------------- | :----: | | **Input Tokens (Per Million)**   | \$2 | | **Output Tokens (Per Million)**   | \$8 | | **Price per 1000 Search Queries**   | \$5 | | **Reasoning Tokens (Per Million)**   | \$3 | *** ## **Offline Model** *For private, factual-based answering without real-time web search.* Offline chat model that does not use search but provides local AI capabilities.\ [Learn more →](../models/models/r1-1776) **Pricing:** | Metric   | Cost   | | --------------------------------- | :-----: | | **Input Tokens (Per Million)**   | \$2   | | **Output Tokens (Per Million)**   | \$8   | *** ### **Tracking Billing Per API Key** You can track billing for each of your API keys by following these steps: 1. Navigate to **Settings** and click on **View Dashboard** ![Navigate to dashboard](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/guides/assets/pricing/view_dashboard.png) 2. Select **Invoice history** > **Invoices** ![View invoice history](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/guides/assets/pricing/view_invoice_history.png) 3. Click on any invoice to view details ![View spend per API key](https://mintlify.s3.us-west-1.amazonaws.com/perplexity/guides/assets/pricing/view_spend_per_api_key.png) 4. Each item from the total bill will have a code at the end (e.g., pro (743S)) * The 4 characters in parentheses are the last 4 characters of your API key # Prompt Guide Source: https://docs.perplexity.ai/guides/prompt-guide ## System Prompt You can use the system prompt to provide instructions related to style, tone, and language of the response. The real-time search component of our models does not attend to the system prompt. **Example of a system prompt** ``` You are a helpful AI assistant. Rules: 1. Provide only the final answer. It is important that you do not include any explanation on the steps below. 2. Do not show the intermediate steps information. Steps: 1. Decide if the answer should be a brief sentence or a list of suggestions. 2. If it is a list of suggestions, first, write a brief and natural introduction based on the original query. 3. Followed by a list of suggestions, each suggestion should be split by two newlines. ``` ## User Prompt You should use the user prompt to pass in the actual query for which you need an answer for. The user prompt will be used to kick off a real-time web search to make sure the answer has the latest and the most relevant information needed. **Example of a user prompt** ``` What are the best sushi restaurants in the world currently? ``` # Web Search Models: General Prompting Guidelines Our web search-powered models combine the capabilities of LLMs with real-time web searches. Understanding how they differ from traditional LLMs will help you craft more effective prompts. ## Best Practices for Prompting Web Search Models Unlike traditional LLMs, our web search models require specificity to retrieve relevant search results. Adding just 2-3 extra words of context can dramatically improve performance. **Good Example**: "Explain recent advances in climate prediction models for urban planning" **Poor Example**: "Tell me about climate models" While few-shot prompting works well for traditional LLMs, it confuses web search models by triggering searches for your examples rather than your actual query. **Good Example**: "Summarize the current research on mRNA vaccine technology" **Poor Example**: "Here's an example of a good summary about vaccines: \[example text]. Now summarize the current research on mRNA vaccines." Craft prompts with search-friendly terms that would appear on relevant web pages. Consider how experts in the field would describe the topic online. **Good Example**: "Compare the energy efficiency ratings of heat pumps vs. traditional HVAC systems for residential use" **Poor Example**: "Tell me which home heating is better" Include critical context to guide the web search toward the most relevant content, but keep prompts concise and focused. **Good Example**: "Explain the impact of the 2023 EU digital markets regulations on app store competition for small developers" **Poor Example**: "What are the rules for app stores?" ## Web Search Model Pitfalls to Avoid Generic prompts lead to scattered web search results and unfocused responses. Always narrow your scope. **Avoid**: "What's happening in AI?" **Instead**: "What are the three most significant commercial applications of generative AI in healthcare in the past year?" Prompting strategies designed for traditional LLMs often don't work well with web search models. Adapt your approach accordingly. **Avoid**: "Act as an expert chef and give me a recipe for sourdough bread. Start by explaining the history of sourdough, then list ingredients, then..." **Instead**: "What's a reliable sourdough bread recipe for beginners? Include ingredients and step-by-step instructions." Complex prompts with multiple unrelated questions can confuse the search component. Focus on one topic per query. **Avoid**: "Explain quantum computing, and also tell me about regenerative agriculture, and provide stock market predictions." **Instead**: "Explain quantum computing principles that might impact cryptography in the next decade." Don't assume the model will search for what you intended without specific direction. Be explicit about exactly what information you need. **Avoid**: "Tell me about the latest developments." **Instead**: "What are the latest developments in offshore wind energy technology announced in the past 6 months?" ### Advanced Techniques We recommend for users *not* to tune language parameters such as `temperature`, as the default settings for these have already been optimized. Adjust model parameters based on your specific needs: * **Search Domain Filter**: Limit results to trusted sources for research-heavy queries. * **Search Context Size**: Use "high" for comprehensive research questions and "low" for simple factual queries. Example configuration for technical documentation: ```json { "search_domain_filter": ["wikipedia.org", "docs.python.org"], "web_search_options": { "search_context_size": "medium" } } ``` ### Tips for Different Query Types | Query Type | Best Practices | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Factual Research** | • Use specific questions • Use search domain filters for academic sources • Consider "high" search context size | | **Creative Content** | • Provide detailed style guidelines in system prompt • Specify tone, voice, and audience | | **Technical Questions** | • Include relevant technical context • Specify preferred programming language/framework • Use domain filters for documentation sites | | **Analysis & Insights** | • Request step-by-step reasoning • Ask for specific metrics or criteria | # Search Context Size Source: https://docs.perplexity.ai/guides/search-context-size-guide The `search_context_size` parameter allows you to control how much search context is retrieved from the web during query resolution, letting you balance cost and comprehensiveness. * Default `search_context_size` is `low` * Selecting `"high"` increases search costs due to more extensive web retrieval. Use `"low"` when cost efficiency is critical. ## Overview The `search_context_size` field—passed via the `web_search_options` object—determines how much search context is retrieved by the Sonar models. This setting can help you optimize for either: * Cost savings with minimal search input (`low`) * Comprehensive answers by maximizing retrieved information (`high`) * A balance of both (`medium`) This flexibility allows teams to tune their API usage to their budget and use case. To enable this feature, include the web\_search\_options.search\_context\_size parameter in your request payload: ```bash "web_search_options": { "search_context_size": "medium" } ``` ## Best Practices **Choosing the Right Context Size** * `low`: Best for short factual queries or when operating under strict token cost constraints. * `medium`: The default and best suited for general use cases. * `high`: Use for deep research, exploratory questions, or when citations and evidence coverage are critical. **Cost Optimization** * Selecting `low` or `medium` can significantly reduce overall token usage, especially at scale. * Consider defaulting to `low` for high-volume endpoints and selectively upgrading to `high` for complex user prompts. Combining with Other Filters * You can use `search_context_size` alongside other features like `search_domain_filter` to further control the scope of search. * Combining `medium` with a focused domain filter often gives a good tradeoff between quality and cost. Performance Considerations * Larger context sizes may slightly increase response latency due to more extensive search and reranking. * If you’re batching queries or supporting real-time interfaces, test with different settings to balance user experience and runtime. ## Examples **1. Minimal Search Context ("low")** This option limits the search context retrieved for the model, reducing cost per request while still producing useful responses for simpler questions. ## Request ```bash cURL 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": "system", "content": "Be precise and concise." }, { "role": "user", "content": "How many stars are there in our galaxy?" } ], "web_search_options": { "search_context_size": "low" } }' ``` ```python python import requests url = "https://api.perplexity.ai/chat/completions" headers = {"Authorization": "Bearer YOUR_API_KEY"} payload = { "model": "sonar", "messages": [ {"role": "system", "content": "Be precise and concise."}, {"role": "user", "content": "How many stars are there in our galaxy?"} ], "web_search_options": { "search_context_size": "low" } } response = requests.post(url, headers=headers, json=payload).json() print(response["choices"][0]["message"]["content"]) ``` **Pro-tip**: Use `low` when cost optimization is more important than answer completeness. **2. Comprehensive Search Context ("high")** This option maximizes the amount of search context used to answer the question, resulting in more thorough and nuanced responses. ## Request ```bash cURL curl --request POST \ --url https://api.perplexity.ai/chat/completions \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "model": "sonar-reasoning-pro", "messages": [ { "role": "system", "content": "Be precise and concise." }, { "role": "user", "content": "Explain the economic causes of the 2008 financial crisis." } ], "web_search_options": { "search_context_size": "high" } }' ``` ```python python import requests url = "https://api.perplexity.ai/chat/completions" headers = {"Authorization": "Bearer YOUR_API_KEY"} payload = { "model": "sonar-reasoning-pro", "messages": [ {"role": "system", "content": "Be precise and concise."}, {"role": "user", "content": "Explain the economic causes of the 2008 financial crisis."} ], "web_search_options": { "search_context_size": "high" } } response = requests.post(url, headers=headers, json=payload).json() print(response["choices"][0]["message"]["content"]) ``` **Pro-tip**: Use `high` for research-heavy or nuanced queries where coverage matters more than cost. ⸻ # Search Domain Filter Guide Source: https://docs.perplexity.ai/guides/search-domain-filters The `search_domain_filter` feature allows you to limit search results to specific domains or exclude certain domains from search results. You can add a maximum of 10 domains to the `search_domain_filter` list. ## Overview The `search_domain_filter` parameter allows you to control which websites are included in or excluded from the search results used by the Sonar models. This feature is particularly useful when you want to: * Restrict search results to trusted sources * Filter out specific domains from search results * Focus research on particular websites Enabling domain filtering can be done by adding a `search_domain_filter` field in the request: ``` "search_domain_filter": [ "", "", ... ] ``` Each entry in the list should be a simple domain name. To exclude a domain, prefix it with a minus sign (`-`). ## Examples ### 1. Allowlist Specific Domains This example shows how to limit search results to only include content from specific domains. **Request** ```python import requests url = "https://api.perplexity.ai/chat/completions" headers = {"Authorization": "Bearer YOUR_API_KEY"} payload = { "model": "sonar-reasoning-pro", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Tell me about the James Webb Space Telescope discoveries."} ], "search_domain_filter": [ "nasa.gov", "wikipedia.org", "space.com" ] } response = requests.post(url, headers=headers, json=payload).json() print(response["choices"][0]["message"]["content"]) ``` **Best Practice**: Use simple domain names (e.g., `wikipedia.org`) without additional elements like `https://` or `www.` prefixes. ### 2. Denylist Specific Domains This example shows how to exclude specific domains from search results by prefixing the domain name with a minus sign (`-`). **Request** ```python import requests url = "https://api.perplexity.ai/chat/completions" headers = {"Authorization": "Bearer YOUR_API_KEY"} payload = { "model": "sonar-deep-research", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What are the latest advancements in renewable energy?"} ], "search_domain_filter": [ "-pinterest.com", "-reddit.com", "-quora.com" ] } response = requests.post(url, headers=headers, json=payload).json() print(response["choices"][0]["message"]["content"]) ``` **Best Practice**: Use simple domain names with a minus prefix (e.g., `-pinterest.com`) to exclude domains from search results. ## Best Practices ### Domain Specification * **Use simple domain names**: Specify domains in their simplest form (e.g., `example.com`) without protocol prefixes (`http://`, `https://`) or subdomain specifiers (`www.`). * **Main domains only**: Using the main domain (e.g., `nytimes.com`) will filter all subdomains as well. ### Filter Optimization * **Be specific**: Use domains that are most relevant to your query to get the best results. * **Combine approaches**: You can mix inclusion and exclusion in the same request (e.g., `["wikipedia.org", "-pinterest.com"]`). * **Limit filter size**: Although you can add up to 10 domains, using fewer, more targeted domains often yields better results. ### Performance Considerations * Adding domain filters may slightly increase response time as the search engine needs to apply additional filtering. * Overly restrictive domain filters might result in fewer search results, potentially affecting the quality of the response. # Structured Outputs Guide Source: https://docs.perplexity.ai/guides/structured-outputs The first request with a new JSON Schema or Regex expects to incur delay on the first token. Typically, it takes 10 to 30 seconds to prepare the new schema, and may result in timeout errors. Once the schema has been prepared, the subsequent requests will not see such delay. ## Overview We currently support two types of structured outputs: **JSON Schema** and **Regex**. LLM responses will work to match the specified format, except for the following cases: * The output exceeds `max_tokens` Enabling the structured outputs can be done by adding a `response_format` field in the request: **JSON Schema** * `response_format: { type: "json_schema", json_schema: {"schema": object} }` . * The schema should be a valid JSON schema object. **Regex** (only available for `sonar` right now) * `response_format: { type: "regex", regex: {"regex": str} }` . * The regex is a regular expression string. We recommend to give the LLM some hints about the output format in the prompts. ## Examples ### 1. Get a response in JSON format **Request** ```python import requests from pydantic import BaseModel class AnswerFormat(BaseModel): first_name: str last_name: str year_of_birth: int num_seasons_in_nba: int url = "https://api.perplexity.ai/chat/completions" headers = {"Authorization": "Bearer YOUR_API_KEY"} payload = { "model": "sonar", "messages": [ {"role": "system", "content": "Be precise and concise."}, {"role": "user", "content": ( "Tell me about Michael Jordan. " "Please output a JSON object containing the following fields: " "first_name, last_name, year_of_birth, num_seasons_in_nba. " )}, ], "response_format": { "type": "json_schema", "json_schema": {"schema": AnswerFormat.model_json_schema()}, }, } response = requests.post(url, headers=headers, json=payload).json() print(response["choices"][0]["message"]["content"]) ``` **Response** ``` {"first_name":"Michael","last_name":"Jordan","year_of_birth":1963,"num_seasons_in_nba":15} ``` ### 2. Use a regex to output the format **Request** ```python python import requests url = "https://api.perplexity.ai/chat/completions" headers = {"Authorization": "Bearer YOUR_API_KEY"} payload = { "model": "sonar", "messages": [ {"role": "system", "content": "Be precise and concise."}, {"role": "user", "content": "What is the IPv4 address of OpenDNS DNS server?"}, ], "response_format": { "type": "regex", "regex": {"regex": r"(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)"}, }, } response = requests.post(url, headers=headers, json=payload).json() print(response["choices"][0]["message"]["content"]) ``` **Response** ``` 208.67.222.222 ``` ## Best Practices ### Generating responses in a JSON Format For Python users, we recommend using the Pydantic library to [generate JSON schema](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_json_schema). **Unsupported JSON Schemas** Recursive JSON schema is not supported. As a result of that, unconstrained objects are not supported either. Here's a few example of unsupported schemas: ``` # UNSUPPORTED! from typing import Any class UnconstrainedDict(BaseModel): unconstrained: dict[str, Any] class RecursiveJson(BaseModel): value: str child: list["RecursiveJson"] ``` ### Generating responses using a regex **Supported Regex** * Characters: `\d`, `\w`, `\s` , `.` * Character classes: `[0-9A-Fa-f]` , `[^x]` * Quantifiers: `*`, `?` , `+`, `{3}`, `{2,4}` , `{3,}` * Alternation: `|` * Group: `( ... )` * Non-capturing group: `(?: ... )` * Positive lookahead: `(?= ... )` * Negative lookahead: `(?! ... )` **Unsupported Regex** * Contents of group: `\1` * Anchors: `^`, `$`, `\b` * Positive look-behind: `(?<= ... )` * Negative look-behind: `(?` section containing reasoning tokens, immediately followed by the structured output. The `response_format` parameter does not remove these reasoning tokens from the output, so the final response will need to be parsed manually. **Sample Response:** ``` I need to provide information about France in a structured JSON format with specific fields: country, capital, population, official_language. For France: - Country: France - Capital: Paris - Population: About 67 million (as of 2023) - Official Language: French Let me format this information as required. {"country":"France","capital":"Paris","population":67750000,"official_language":"French"} ``` For a reusable implementation to extract JSON from reasoning model outputs, see our [example utility on GitHub](https://github.com/ppl-ai/api-discussion/blob/main/utils/extract_json_reasoning_models.py). # Rate Limits and Usage Tiers Source: https://docs.perplexity.ai/guides/usage-tiers We follow the usage tier system below to set rate limits and give access to beta features for our APIs. You can check your usage tier by going to your [API settings page](https://www.perplexity.ai/settings/api). ## Usage Tiers | Tier | Credit Purchase (all time) | | -------- | -------------------------- | | `Tier 0` | - | | `Tier 1` | \$50 | | `Tier 2` | \$250 | | `Tier 3` | \$500 | | `Tier 4` | \$1000 | | `Tier 5` | \$5000 | The tiers are based on cumulative purchases on a given account ## Rate Limits and Beta Features | Model | Requests per minute (RPM) | Beta Features | | --------------------- | ------------------------- | ------------------------------------------------------------------- | | `sonar-deep-research` | 5 | related questions, structured outputs | | `sonar-reasoning-pro` | 50 | images, related questions, search domain filter, structured outputs | | `sonar-reasoning` | 50 | images, related questions, search domain filter, structured outputs | | `sonar-pro` | 50 | images, related questions, search domain filter, structured outputs | | `sonar` | 50 | images, related questions, search domain filter, structured outputs | | `r1-1776` | 50 | structured outputs | | Model | Requests per minute (RPM) | Beta Features | | --------------------- | ------------------------- | ------------------------------------------------------------------- | | `sonar-deep-research` | 5 | related questions, structured outputs | | `sonar-reasoning-pro` | 50 | images, related questions, search domain filter, structured outputs | | `sonar-reasoning` | 50 | images, related questions, search domain filter, structured outputs | | `sonar-pro` | 50 | images, related questions, search domain filter, structured outputs | | `sonar` | 50 | images, related questions, search domain filter, structured outputs | | `r1-1776` | 50 | structured outputs | | Model | Requests per minute (RPM) | Beta Features | | --------------------- | ------------------------- | ------------------------------------------------------------------- | | `sonar-deep-research` | 5 | related questions, structured outputs | | `sonar-reasoning-pro` | 500 | images, related questions, search domain filter, structured outputs | | `sonar-reasoning` | 500 | images, related questions, search domain filter, structured outputs | | `sonar-pro` | 500 | images, related questions, search domain filter, structured outputs | | `sonar` | 500 | images, related questions, search domain filter, structured outputs | | `r1-1776` | 500 | structured outputs | | Model | Requests per minute (RPM) | Beta Features | | --------------------- | ------------------------- | ------------------------------------------------------------------- | | `sonar-deep-research` | 5 | related questions, structured outputs | | `sonar-reasoning-pro` | 1000 | images, related questions, search domain filter, structured outputs | | `sonar-reasoning` | 1000 | images, related questions, search domain filter, structured outputs | | `sonar-pro` | 1000 | images, related questions, search domain filter, structured outputs | | `sonar` | 1000 | images, related questions, search domain filter, structured outputs | | `r1-1776` | 1000 | structured outputs | | Model | Requests per minute (RPM) | Beta Features | | --------------------- | ------------------------- | ------------------------------------------------------------------- | | `sonar-deep-research` | 5 | related questions, structured outputs | | `sonar-reasoning-pro` | 2000 | images, related questions, search domain filter, structured outputs | | `sonar-reasoning` | 2000 | images, related questions, search domain filter, structured outputs | | `sonar-pro` | 2000 | images, related questions, search domain filter, structured outputs | | `sonar` | 2000 | images, related questions, search domain filter, structured outputs | | `r1-1776` | 2000 | structured outputs | | Model | Requests per minute (RPM) | Beta Features | | --------------------- | ------------------------- | ------------------------------------------------------------------- | | `sonar-deep-research` | 100 | related questions, structured outputs | | `sonar-reasoning-pro` | 2000 | images, related questions, search domain filter, structured outputs | | `sonar-reasoning` | 2000 | images, related questions, search domain filter, structured outputs | | `sonar-pro` | 2000 | images, related questions, search domain filter, structured outputs | | `sonar` | 2000 | images, related questions, search domain filter, structured outputs | | `r1-1776` | 2000 | structured outputs | 1. `r1-1776` is an offline chat model that does not use our search subsystem so image search, related questions and search domain filter aren't available for it 2. Rate Limit for`sonar-deep-research`increases to 100rpm in Tier - 5 # null Source: https://docs.perplexity.ai/home export function openSearch() { document.getElementById("search-bar-entry").click(); }
Sonar Ecru

Welcome to Sonar by Perplexity

Power your products with unparalleled real-time, web-wide research and Q\&A capabilities.

Get Started

Explore the docs

Start using the API in minutes Integrate the API into your workflows Explore pricing of the API Understand API rate limits, features, and restrictions Frequently asked questions about the API Track the status of our services including the API
# Models Source: https://docs.perplexity.ai/models/model-cards Explore all available models and compare their capabilities. ## Search Models *Models designed to retrieve and synthesize information efficiently.* Advanced search offering with grounding, supporting complex queries and follow-ups.\ [Learn more →](./models/sonar-pro) Lightweight, cost-effective search model with grounding.\ [Learn more →](./models/sonar) Best suited for quick factual queries, topic summaries, product comparisons, and current events where simple information retrieval and synthesis is needed without complex reasoning. Not ideal for multi-step analyses, exhaustive research on broad topics, or projects requiring detailed instructions or comprehensive reports across multiple sources. ## Research Models *Models that conduct in-depth analysis and generate detailed reports.* Expert-level research model conducting exhaustive searches and generating comprehensive reports.\ [Learn more →](./models/sonar-deep-research) Ideal for comprehensive topic reports, in-depth analysis with exhaustive web research, and projects requiring synthesis of multiple information sources into cohesive reports like market analyses or literature reviews. Avoid using for quick queries, simple lookups, or time-sensitive tasks, as these models may take 30+ minutes to process and are excessive when depth isn't required. ## Reasoning Models *Models that excel at complex, multi-step tasks.* Premier reasoning offering powered by DeepSeek R1 with Chain of Thought (CoT).\ [Learn more →](./models/sonar-reasoning-pro) Fast, real-time reasoning model designed for quick problem-solving with search.\ [Learn more →](./models/sonar-reasoning) Excellent for complex analyses requiring step-by-step thinking, tasks needing strict adherence to instructions, information synthesis across sources, and logical problem-solving that demands informed recommendations. Not recommended for simple factual queries, basic information retrieval, exhaustive research projects (use Research models instead), or when speed takes priority over reasoning quality. ## Offline Models *Chat models that do not use our search subsystem.* A version of DeepSeek R1 post-trained for uncensored, unbiased, and factual information.\ [Learn more →](./models/r1-1776) Perfect for creative content generation, tasks not requiring up-to-date web information, scenarios favoring traditional LLM techniques, and maintaining conversation context without search interference. Unsuitable for queries needing current web information, tasks benefiting from search-augmented generation, or research projects requiring integration of multiple external sources. *** ## Context Length per Model | Model | Context Length | Model Type | | --------------------- | -------------- | --------------- | | `sonar-deep-research` | 128k | Chat Completion | | `sonar-reasoning-pro` | 128k | Chat Completion | | `sonar-reasoning` | 128k | Chat Completion | | `sonar-pro` | 200k | Chat Completion | | `sonar` | 128k | Chat Completion | | `r1-1776` | 128k | Chat Completion | * `sonar-pro` has a max output token limit of 8k. * The reasoning models output Chain of Thought (CoT) responses. * `r1-1776` is an offline chat model that does not use our search subsystem. # Application Status Source: https://docs.perplexity.ai/system-status/system-status You can check the status of our services [here](https://status.perplexity.com/). If you experience any issues or have any questions, please contact us at [api@perplexity.ai](mailto:api@perplexity.ai) or flag a bug report in our [Discord](https://discord.com/invite/perplexity-ai) channel.