# Perplexity

## Docs

- [Chat Completions](https://docs.perplexity.ai/api-reference/chat-completions): Generates a model's response for the given chat conversation.
- [Changelog](https://docs.perplexity.ai/changelog/changelog)
- [Forum](https://docs.perplexity.ai/discussions/discussions)
- [Frequently Asked Questions](https://docs.perplexity.ai/faq/faq)
- [Initial Setup](https://docs.perplexity.ai/guides/getting-started): Register and make a successful API request
- [Supported Models](https://docs.perplexity.ai/guides/model-cards)
- [PerplexityBot](https://docs.perplexity.ai/guides/perplexitybot): We strive to improve our service every day. To provide the best search experience, we need to collect data. We use web crawlers to gather information from the internet and index it for our search engine. 
- [Pricing](https://docs.perplexity.ai/guides/pricing)
- [Rate Limits](https://docs.perplexity.ai/guides/rate-limits)
- [null](https://docs.perplexity.ai/home)
- [Application Status](https://docs.perplexity.ai/system-status/system-status)


# Chat Completions

post /chat/completions
Generates a model's response for the given chat conversation.



# Changelog



<AccordionGroup>
  <Accordion title="Citations Public Release and Increased Default Rate Limits" description="November 2024">
    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)
  </Accordion>

  <Accordion title="Introducing New and Improved Sonar Models." description="July 2024">
    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
  </Accordion>

  <Accordion title="Model Deprecation Notice" description="April 2024">
    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`
  </Accordion>

  <Accordion title="Cheaper Output Tokens" description="February 2024">
    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.
  </Accordion>

  <Accordion title="API Updates" description="February 2024">
    **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.
  </Accordion>

  <Accordion title="New Model: mixtral-8x7b-instruct" description="January 2024">
    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.
  </Accordion>

  <Accordion title="Online LLMs and general availability for pplx-api" description="December 2023">
    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.
  </Accordion>

  <Accordion title="Models removed: replit-code-v1.5-3b and openhermes-2-mistral-7b" description="December 2023">
    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`!
  </Accordion>

  <Accordion title="Versioning" description="November 2023">
    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).
  </Accordion>
</AccordionGroup>


# Forum



We host our dicsussions on GitHub. You can access our GitHub discussion forum [here](https://github.com/ppl-ai/api-discussion/discussions).


# Frequently Asked Questions



<AccordionGroup>
  <Accordion title="Why are the results from the API different from the UI? ">
    The answers you get from the API should closely resemble the default search answers in the UI. The API uses the same search subsystem as the UI with small differences in configuration. However, you could be seeing differences between the API and UI due to the following reasons:

    **Pro Search**

    The API doesn't support Pro Search today. Pro Search uses a multi-step reasoning process which increases the quality of the answer.

    **Using third party models**

    At this time, the API only supports the Sonar models. Using other third party models like GPT-4o/Sonnet 3.5 in the UI could lead to diverging results.

    **Tuning of sampling parameters (presence\_penalty, top\_p etc) and system prompt in the API**

    Our defaults are tuned to give the best results from the API and match the default search experience in the UI. We give users the power to tune the API to their respective use cases and custom tuning to specific use cases might lead to less generalization of the API/different results vs the UI. We recommend not to explicitly provide sampling parameters in your API requests if you want parity with the default experience in the UI.
  </Accordion>

  <Accordion title="Will user data submitted through the API be used for model training or other purposes?">
    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.
  </Accordion>

  <Accordion title="Does the API currently support web browsing?">
    Yes! You can use the [Perplexity Sonar Models](https://docs.perplexity.ai/guides/model-cards), which leverage information from Perplexity’s search index and the public internet.
  </Accordion>

  <Accordion title="What are the limitations to the number of API calls?">
    You can find our [rate limits here](https://docs.perplexity.ai/guides/rate-limits).
  </Accordion>

  <Accordion title="What's the best way to stay up to date with API updates?">
    We email users about new developments and also post in the [changelog](/changelog.mdx).
  </Accordion>

  <Accordion title="Is there any way to get a token rate limit increase?">
    Please fillout this [form](https://perplexity.typeform.com/apiaccessform?typeform-source=docs.perplexity.ai) if you require a rate limit increase for commercial purposes. We consider rate limit increases on a case by case basis.
  </Accordion>

  <Accordion title="How should I respond to 401: Authorization errors?">
    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.
  </Accordion>

  <Accordion title="Do you support fine-tuning?">
    Currently, we do not support fine-tuning.
  </Accordion>

  <Accordion title="I have another question or an issue">
    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.
  </Accordion>

  <Accordion title="Does Perplexity provide service quality assurances such as service uptime, frequency of failures, and target recovery time in the event of a failure?">
    We do not guarantee this at the moment.
  </Accordion>
</AccordionGroup>


# Initial Setup

Register and make a successful API request

## Registration

*   Start by visiting the [API Settings page](https://www.perplexity.ai/pplx-api)

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/perplexity/images/24cc167-Screenshot_2023-11-28_at_6.19.34_PM.png" />
</Frame>

*   Register your credit card to get started

<Note>
  This step will not charge your credit card. It just stores payment information for later API usage.
</Note>

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/perplexity/images/50d9caa-Screenshot_2023-11-28_at_6.23.21_PM.png" />
</Frame>

## Generate an API key

*   Every API call needs a valid API key

<Info>
  The API key is a long-lived access token that can be used until it is manually refreshed or deleted.
</Info>

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/perplexity/images/c83bb1f-Screenshot_2023-11-28_at_6.41.40_PM.png" />
</Frame>

Send the API key as a bearer token in the Authorization header with each API request.

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

## Make your API call

*   The API is conveniently OpenAI client-compatible for easy integration with existing applications.

```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": "llama-3.1-sonar-small-128k-online",
  "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="llama-3.1-sonar-large-128k-online",
    messages=messages,
)
print(response)

# chat completion with streaming
response_stream = client.chat.completions.create(
    model="llama-3.1-sonar-large-128k-online",
    messages=messages,
    stream=True,
)
for response in response_stream:
    print(response)
```


# Supported Models



| Model                               | Parameter Count | Context Length | Model Type      |
| ----------------------------------- | --------------- | -------------- | --------------- |
| `llama-3.1-sonar-small-128k-online` | 8B              | 127,072        | Chat Completion |
| `llama-3.1-sonar-large-128k-online` | 70B             | 127,072        | Chat Completion |
| `llama-3.1-sonar-huge-128k-online`  | 405B            | 127,072        | Chat Completion |

<Note>
  The search component of our models do not attend to the system prompt. You can use the system prompt to provide instructions related to style, tone, and language of the response.
</Note>

<Info>
  **Beta Access**: The Online LLMs have some features in closed beta - to request access to them, please fill out this [form](https://perplexity.typeform.com/apiaccessform?typeform-source=docs.perplexity.ai).
</Info>


# PerplexityBot

We strive to improve our service every day. To provide the best search experience, we need to collect data. We use web crawlers to gather information from the internet and index it for our search engine. 

You can identify our web crawler by its user agent

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

## Customizing access

### Disallow PerplexityBot

To prevent PerplexityBot from accessing your site data, add a record to your site's robots.txt

```JSX JSX
User-Agent: PerplexityBot
Disallow: /
```

### Custom access rules

You can also customize access, disallowing data retrieval only from specific paths.

```JSX JSX
User-Agent: PerplexityBot
Allow: /public/
Disallow: /private/
```


# Pricing



| Model                               | Price per 1000 requests | Price per 1M tokens |
| ----------------------------------- | ----------------------- | ------------------- |
| `llama-3.1-sonar-small-128k-online` | \$5                     | \$0.2               |
| `llama-3.1-sonar-large-128k-online` | \$5                     | \$1                 |
| `llama-3.1-sonar-huge-128k-online`  | \$5                     | \$5                 |

<Info>
  The pricing for the models is a combination of the fixed price + the variable price based on input and output tokens in a request.
</Info>


# Rate Limits



| Model                               | Request Rate Limit |
| ----------------------------------- | ------------------ |
| `llama-3.1-sonar-small-128k-online` | 50/min             |
| `llama-3.1-sonar-large-128k-online` | 50/min             |
| `llama-3.1-sonar-huge-128k-online`  | 50/min             |

<Note> We limit model usage if the request rate exceeds the limit for any given model. </Note>

<Info>
  To request elevated rate limits, fill out this [form](https://perplexity.typeform.com/apiaccessform).
</Info>


# null



export function openSearch() {
  document.getElementById('search-bar-entry').click();
}

<div className="relative w-full flex items-center justify-center" style={{ height: '24rem', overflow: 'hidden'}}>
  <div className="absolute inset-0 bg-primary dark:bg-primary-light" style={{opacity: 0.05 }} />

  <div style={{ position: 'absolute', textAlign: 'center', padding: '0 1rem' }}>
    <div
      className="text-gray-900 dark:text-gray-200"
      style={{
      fontWeight: '700',
      fontSize: '40px',
      margin: '0',
      }}
    >
      Welcome to Perplexity API
    </div>

    <p
      className="prose prose-gray dark:prose-invert"
      style={{
       marginTop: '1rem',
      fontWeight: '400',
      fontSize: '16px',
      maxWidth: '42rem'
      }}
    >
      Our models give you accurate factual answers to all your questions
    </p>

    <p
      className="prose prose-gray dark:prose-invert"
      style={{
       marginTop: '1rem',
      fontWeight: '400',
      fontSize: '16px',
      maxWidth: '42rem'
      }}
    >
      <a href="https://docs.perplexity.ai/guides/getting-started" className="text-primary dark:text-primary-light">**Get Started >**</a>
    </p>

    <div className="flex items-center justify-center" />
  </div>
</div>

<div
  style={{marginTop: '6rem', marginBottom: '8rem', maxWidth: '70rem', marginLeft: 'auto',
  marginRight: 'auto', paddingLeft: '1.25rem',
  paddingRight: '1.25rem' }}
>
  <div
    className="text-gray-900 dark:text-gray-200"
    style={{
    textAlign: 'center',
    fontSize: '24px',
    fontWeight: '400',
    marginBottom: '3rem',
    }}
  >
    Explore the API
  </div>

  <h2 className="text-gray-900 dark:text-gray-200" style={{marginTop: '2rem', marginBottom: '2rem', fontWeight: '500'}} />

  <CardGroup cols={2}>
    <Card title="Quickstart" icon="play" href="https://docs.perplexity.ai/guides/getting-started" horizontal>
      Start using the API in minutes
    </Card>

    <Card title="API Reference" icon="webhook" iconType="solid" href="/api-reference" horizontal>
      Integrate the API into your workflows
    </Card>

    <Card title="Help" icon="circle-question" href="/faq/faq" horizontal>
      Frequently asked questions about the API
    </Card>

    <Card title="System Status" icon="monitor-waveform" href="https://status.perplexity.com/" horizontal>
      Track the status of our services inlcuding the API
    </Card>
  </CardGroup>
</div>


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