Perplexity API Chat Completions

https://docs.perplexity.ai/api-reference
Admin
Generates a model’s response for the given chat conversation using the Perplexity API.
Tokens:26,475
Snippets:121
Trust Score:9.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Async Sonar Chat Completion Request Example

Source: https://docs.perplexity.ai/api-reference/async-sonar-post

This example demonstrates the structure of a request body for creating an asynchronous chat completion using the sonar-deep-research model. It includes messages with roles and content.

```yaml
request:
  model: sonar-deep-research
  messages:
    - role: <string>
      content: <string>
```

--------------------------------

### ReasoningStartedEvent

Source: https://docs.perplexity.ai/api-reference/agent-post

Signals the start of the agent's reasoning or searching process. Includes the type and sequence number.

```APIDOC
## ReasoningStartedEvent

### Description
Signals the model has started reasoning/searching.

### Properties
- **type** (EventType) - Required - Must be 'response.reasoning.started'.
- **sequence_number** (integer) - Required - Monotonically increasing sequence number for event ordering.
- **thought** (string) - Optional - The agent's thought process.
```

--------------------------------

### Search API Response Example

Source: https://docs.perplexity.ai/api-reference/search-post

This JSON object illustrates the structure of the response returned by the Search API. It includes a ranked 'results' array, with each item containing 'title', 'url', 'snippet', and optional 'date' and 'last_updated' fields.

```json
{
  "results": [
    {
      "title": "Example Article Title",
      "url": "https://example.com/article",
      "snippet": "A short excerpt from the article relevant to the query...",
      "date": "2025-01-23",
      "last_updated": "2025-09-25"
    },
    {
      "title": "Another Relevant Source",
      "url": "https://example.org/source",
      "snippet": "Another excerpt showing the structured result format.",
      "date": "2024-11-15",
      "last_updated": "2025-08-12"
    },
    {
      "title": "Third Result",
      "url": "https://example.net/page",
      "snippet": "A third result demonstrating the ranked array structure.",
      "date": "2024-09-10",
      "last_updated": "2025-07-03"
    }
  ],
  "id": "e38104d5-6bd7-4d82-bc4e-0a21179d1f77"
}
```

--------------------------------

### OpenAPI Specification for List Async Chat Completions

Source: https://docs.perplexity.ai/api-reference/async-sonar-get

This OpenAPI 3.1.0 specification defines the GET /v1/async/sonar endpoint for listing asynchronous chat completion requests. It includes request and response schemas, security schemes, and error handling.

```yaml
openapi: 3.1.0
info:
  title: Perplexity AI API
  description: Perplexity AI API
  version: 1.0.0
servers:
  - url: https://api.perplexity.ai
    description: Perplexity AI API
security: []
paths:
  /v1/async/sonar:
    get:
      summary: List Async Chat Completions
      description: >-
        Retrieve a list of all asynchronous chat completion requests for a given
        user.
      operationId: list_async_chat_completions_async_chat_completions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAsyncApiChatCompletionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    ListAsyncApiChatCompletionsResponse:
      properties:
        next_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Token
        requests:
          items:
            $ref: '#/components/schemas/AsyncApiChatCompletionsResponseSummary'
          type: array
          title: Requests
      type: object
      required:
        - requests
      title: ListAsyncApiChatCompletionsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AsyncApiChatCompletionsResponseSummary:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: integer
          title: Created At
        started_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Started At
        completed_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Completed At
        failed_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Failed At
        model:
          type: string
          title: Model
        status:
          $ref: '#/components/schemas/AsyncProcessingStatus'
      type: object
      required:
        - id
        - created_at
        - model
        - status
      title: AsyncApiChatCompletionsResponseSummary
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AsyncProcessingStatus:
      type: string
      enum:
        - CREATED
        - IN_PROGRESS
        - COMPLETED
        - FAILED
      title: AsyncProcessingStatus
      description: Status enum for async processing.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

```

--------------------------------

### Computer Usage Analytics Endpoint Definition

Source: https://docs.perplexity.ai/api-reference/computer-analytics-usage-get

This OpenAPI definition outlines the GET request for computer usage analytics. It specifies parameters like dataset, time windows, bucket width, and pagination. The response includes bucketed usage data.

```yaml
openapi: 3.1.0
info:
  title: Perplexity AI API
  description: Perplexity AI API
  version: 1.0.0
servers:
  - url: https://api.perplexity.ai
    description: Perplexity AI API
security: []
paths:
  /v1/analytics/computer/usage:
    get:
      summary: Computer Usage Analytics
      description: >-
        Returns your organization's Computer usage analytics as a bucketed time
        series for a single dataset. Requires an organization analytics API key,
        generated by an org admin from Settings → Organization → Computer in the
        Perplexity web app. Only complete UTC grid buckets are returned:
        start_time snaps down to its bucket, and the in-progress bucket is never
        included.
      operationId: getComputerUsageAnalytics
      parameters:
        - name: dataset
          in: query
          required: true
          description: The dataset to query.
          schema:
            type: string
            enum:
              - credit_usage
              - connectors
              - artifacts
              - skills
              - spaces
              - workflows
              - task_durations
        - name: start_time
          in: query
          required: true
          description: >-
            Window start in unix seconds (UTC), inclusive. Snapped down to the
            bucket grid, so the first bucket can include usage from before this
            time.
          schema:
            type: integer
            minimum: 0
        - name: end_time
          in: query
          required: false
          description: >-
            Window end in unix seconds (UTC), exclusive. Defaults to now; future
            values are capped at now. The window may span at most 90 days.
          schema:
            type: integer
            minimum: 0
        - name: bucket_width
          in: query
          required: false
          description: Bucket size. Buckets align to the UTC grid.
          schema:
            type: string
            enum:
              - 1d
              - 1h
            default: 1d
        - name: limit
          in: query
          required: false
          description: 'Buckets per page. 1d: default 7, max 31. 1h: default 24, max 168.'
          schema:
            type: integer
        - name: page
          in: query
          required: false
          description: >-
            Opaque pagination cursor from a previous response's next_page. Valid
            only with the same query parameters it was issued for.
          schema:
            type: string
        - name: user_email
          in: query
          required: false
          description: >-
            Restrict results to a single member of your organization. Emails
            that don't match a current member return a generic 400.
          schema:
            type: string
            format: email
      responses:
        '200':
          description: >-
            Bucketed usage for the requested window. Buckets without data carry
            count 0; the analytics store syncs periodically, so a zero in a
            recent bucket can mean the data hasn't synced yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputerUsageResponse'
              example:
                data:
                  - start_time: 1746057600
                    end_time: 1746144000
                    count: 350
                    by_category:
                      - category: paid
                        count: 250
                      - category: promo
                        count: 80
                has_more: false
                next_page: null
        '400':
          description: >-
            Invalid parameters (type: bad_request) or semantically invalid
            request (type: invalid_request) — e.g. start_time after end_time, a
            window over 90 days, a misused pagination cursor, or a user_email
            that doesn't match a member of the organization.
          content:
            application/json:

```

--------------------------------

### Get Computer Usage Analytics

Source: https://docs.perplexity.ai/api-reference/computer-analytics-usage-get

Returns your organization's Computer usage analytics as a bucketed time series for a single dataset. Requires an organization analytics API key. Only complete UTC grid buckets are returned.

```APIDOC
## GET /v1/analytics/computer/usage

### Description
Returns your organization's Computer usage analytics as a bucketed time series for a single dataset. Requires an organization analytics API key, generated by an org admin from Settings → Organization → Computer in the Perplexity web app. Only complete UTC grid buckets are returned: start_time snaps down to its bucket, and the in-progress bucket is never included.

### Method
GET

### Endpoint
/v1/analytics/computer/usage

### Parameters
#### Query Parameters
- **dataset** (string) - Required - The dataset to query. Enum: credit_usage, connectors, artifacts, skills, spaces, workflows, task_durations
- **start_time** (integer) - Required - Window start in unix seconds (UTC), inclusive. Snapped down to the bucket grid, so the first bucket can include usage from before this time.
- **end_time** (integer) - Optional - Window end in unix seconds (UTC), exclusive. Defaults to now; future values are capped at now. The window may span at most 90 days.
- **bucket_width** (string) - Optional - Bucket size. Buckets align to the UTC grid. Enum: 1d, 1h. Default: 1d
- **limit** (integer) - Optional - Buckets per page. 1d: default 7, max 31. 1h: default 24, max 168.
- **page** (string) - Optional - Opaque pagination cursor from a previous response's next_page. Valid only with the same query parameters it was issued for.
- **user_email** (string) - Optional - Restrict results to a single member of your organization. Emails that don't match a current member return a generic 400.

### Response
#### Success Response (200)
- **data** (array) - Bucketed usage for the requested window. Buckets without data carry count 0; the analytics store syncs periodically, so a zero in a recent bucket can mean the data hasn't synced yet.
  - **start_time** (integer) - The start of the bucket.
  - **end_time** (integer) - The end of the bucket.
  - **count** (integer) - The total count for the bucket.
  - **by_category** (array) - Breakdown of counts by category.
    - **category** (string) - The category name.
    - **count** (integer) - The count for this category.
- **has_more** (boolean) - Indicates if there are more pages of results.
- **next_page** (string) - Opaque cursor for the next page of results, or null if there are no more pages.

#### Response Example
{
  "data": [
    {
      "start_time": 1746057600,
      "end_time": 1746144000,
      "count": 350,
      "by_category": [
        {
          "category": "paid",
          "count": 250
        },
        {
          "category": "promo",
          "count": 80
        }
      ]
    }
  ],
  "has_more": false,
  "next_page": null
}

#### Error Response (400)
- **type** (string) - Indicates the type of error (e.g., bad_request, invalid_request).
- **message** (string) - A description of the error.
```

--------------------------------

### Get Computer Usage Data

Source: https://docs.perplexity.ai/api-reference/computer-analytics-usage-get

Retrieves computer usage data within a specified time window. You can filter by various parameters to get specific insights.

```APIDOC
## GET /analytics/computer/usage

### Description
Retrieves computer analytics usage data.

### Method
GET

### Endpoint
/analytics/computer/usage

### Query Parameters
- **start_time** (integer) - Required - Unix seconds (UTC) for the start of the window, inclusive.
- **end_time** (integer) - Required - Unix seconds (UTC) for the end of the window, exclusive.
- **page** (string) - Optional - Cursor for the next page.

### Response
#### Success Response (200)
- **data** (array) - Array of ComputerUsageBucket objects.
- **has_more** (boolean) - Indicates if more data is available.
- **next_page** (string | null) - Cursor for the next page.

#### Response Example
```json
{
  "data": [
    {
      "start_time": 1678886400,
      "end_time": 1678890000,
      "count": 150,
      "by_category": [
        {
          "category": "browser",
          "count": 100
        },
        {
          "category": "editor",
          "count": 50
        }
      ]
    }
  ],
  "has_more": true,
  "next_page": "some_cursor_string"
}
```

### Error Handling
- **400 Bad Request**: Invalid request parameters, e.g., `start_time` must be before `end_time`.
- **401 Unauthorized**: Missing or invalid API key.
- **404 Not Found**: Computer Analytics API is not enabled for this organization.
- **429 Too Many Requests**: Rate limit exceeded.
```

--------------------------------

### List Available Models

Source: https://docs.perplexity.ai/api-reference/models-get

This OpenAPI specification defines the GET /v1/models endpoint. It returns a list of model identifiers compatible with the Agent API, formatted similarly to OpenAI's List Models response. Use the `id` field from the response as the `model` parameter in subsequent API calls.

```yaml
openapi: 3.1.0
info:
  title: Perplexity AI API
  description: Perplexity AI API
  version: 1.0.0
servers:
  - url: https://api.perplexity.ai
    description: Perplexity AI API
security: []
paths:
  /v1/models:
    get:
      summary: List Models
      description: >-
        List the models available for the Agent API. Returns model identifiers
        that can be used with the `POST /v1/agent` endpoint. The response
        follows the OpenAI List Models format for compatibility with third-party
        tools.
      operationId: listModels
      responses:
        '200':
          description: Successful response with the list of available models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
              example:
                object: list
                data:
                  - id: anthropic/claude-opus-4-8
                    object: model
                    created: 0
                    owned_by: anthropic
                  - id: anthropic/claude-sonnet-4-6
                    object: model
                    created: 0
                    owned_by: anthropic
                  - id: openai/gpt-5.5
                    object: model
                    created: 0
                    owned_by: openai
                  - id: google/gemini-3.1-flash-lite
                    object: model
                    created: 0
                    owned_by: google
                  - id: google/gemini-3.1-flash-lite-preview
                    object: model
                    created: 0
                    owned_by: google
                  - id: google/gemini-3.5-flash
                    object: model
                    created: 0
                    owned_by: google
                  - id: xai/grok-4.3
                    object: model
                    created: 0
                    owned_by: xai
                  - id: xai/grok-4.20-reasoning
                    object: model
                    created: 0
                    owned_by: xai
                  - id: xai/grok-4.20-non-reasoning
                    object: model
                    created: 0
                    owned_by: xai
                  - id: xai/grok-4.20-multi-agent
                    object: model
                    created: 0
                    owned_by: xai
                  - id: perplexity/sonar
                    object: model
                    created: 0
                    owned_by: perplexity
      security: []
components:
  schemas:
    ListModelsResponse:
      type: object
      description: >-
        Response from the List Models endpoint. Contains a list of available
        models.
      properties:
        object:
          type: string
          description: The object type, which is always `list`.
          enum:
            - list
          example: list
        data:
          type: array
          description: A list of model objects.
          items:
            $ref: '#/components/schemas/Model'
      required:
        - object
        - data
    Model:
      type: object
      description: Represents a model available through the Agent API.
      properties:
        id:
          type: string
          description: >-
            The model identifier in `provider/model-name` format. Use this value
            as the `model` parameter in Agent API requests.
          example: openai/gpt-5.5
        object:
          type: string
          description: The object type, which is always `model`.
          enum:
            - model
          example: model
        created:
          type: integer
          description: The Unix timestamp (in seconds) when the model was created.
          example: 0
        owned_by:
          type: string
          description: >-
            The provider that owns the model (e.g. `openai`, `anthropic`,
            `google`, `perplexity`, `xai`, `nvidia`).
          example: openai
      required:
        - id
        - object
        - created
        - owned_by
```

--------------------------------

### ResponseInProgressEvent

Source: https://docs.perplexity.ai/api-reference/agent-post

Indicates that the response processing has started. This event is emitted when the API begins generating a response.

```APIDOC
## ResponseInProgressEvent

### Description
Emitted when response processing has started. This event signifies the beginning of response generation.

### Properties
- **type** (string) - Required - The event type, which is "response.in_progress".
- **sequence_number** (integer) - Required - Monotonically increasing sequence number for event ordering.
- **response** (ResponsesResponse) - Optional - Details about the ongoing response.
```

--------------------------------

### OpenAPI Specification for Async Chat Completion

Source: https://docs.perplexity.ai/api-reference/async-sonar-api-request-get

This OpenAPI 3.1.0 specification defines the GET endpoint for retrieving asynchronous chat completion responses. It outlines the request parameters, response schemas for success (200) and validation errors (422), and the structure of the API response including IDs, timestamps, status, and the completion content.

```yaml
get /v1/async/sonar/{api_request}
openapi: 3.1.0
info:
  title: Perplexity AI API
  description: Perplexity AI API
  version: 1.0.0
servers:
  - url: https://api.perplexity.ai
    description: Perplexity AI API
security: []
paths:
  /v1/async/sonar/{api_request}:
    get:
      summary: Get Async Chat Completion
      description: Retrieve the response for a given asynchronous chat completion request.
      operationId: >-
        get_async_chat_completion_response_async_chat_completions__api_request__get
      parameters:
        - name: api_request
          in: path
          required: true
          schema:
            type: string
            title: Api Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncApiChatCompletionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    AsyncApiChatCompletionsResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the async request
        model:
          type: string
          title: Model
          description: Model used for the request
        created_at:
          type: integer
          title: Created At
          description: Unix timestamp when the request was created
        started_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Started At
          description: Unix timestamp when processing started
        completed_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Completed At
          description: Unix timestamp when processing completed
        response:
          anyOf:
            - $ref: '#/components/schemas/CompletionResponse'
            - type: 'null'
        failed_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Failed At
          description: Unix timestamp when the request failed (if applicable)
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
          description: Error message if the request failed
        status:
          $ref: '#/components/schemas/AsyncProcessingStatus'
          description: Current processing status of the request
      type: object
      required:
        - id
        - model
        - created_at
        - status
      title: AsyncApiChatCompletionsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CompletionResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the completion
        model:
          type: string
          title: Model
          description: Model used for generation
        created:
          type: integer
          title: Created
          description: Unix timestamp when the completion was created
        usage:
          anyOf:
            - $ref: '#/components/schemas/UsageInfo'
            - type: 'null'
        object:
          type: string
          title: Object
          description: Object type identifier
          default: chat.completion
        choices:
          items:
            $ref: '#/components/schemas/Choice'
          type: array
          title: Choices
          description: Array of completion choices
        citations:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Citations
          description: URLs of sources used to generate the response
        search_results:
          anyOf:
            - items:
                $ref: '#/components/schemas/ApiPublicSearchResult'
              type: array
            - type: 'null'
          title: Search Results
          description: Search results used for context in the response
        images:
          anyOf:
            - items:
                $ref: '#/components/schemas/ImageResult'
              type: array
            - type: 'null'
          title: Images
          description: Array of images returned when return_images is true
        related_questions:
          anyOf:
            - items:
                type: string

```

--------------------------------

### FinanceSearchTool Configuration

Source: https://docs.perplexity.ai/api-reference/agent-post

Configuration for the FinanceSearchTool, enabling the agent to perform financial searches. This tool is identified by its type.

```APIDOC
## FinanceSearchTool

### Description
Finance search tool configuration for the Agent API. Enables the agent to perform financial searches.

### Properties
- **type** (string) - Required - Must be 'finance_search'.
```

--------------------------------

### FetchUrlTool Configuration

Source: https://docs.perplexity.ai/api-reference/agent-post

Configuration for the FetchUrlTool, allowing the agent to fetch content from specified URLs. It includes a maximum limit for the number of URLs to fetch.

```APIDOC
## FetchUrlTool

### Description
Configuration for the FetchUrlTool, allowing the agent to fetch content from specified URLs. It includes a maximum limit for the number of URLs to fetch.

### Properties
- **type** (string) - Required - Must be 'fetch_url'.
- **max_urls** (integer) - Optional - Maximum number of URLs to fetch per tool call. Minimum: 1, Maximum: 10.
```

--------------------------------

### Tool

Source: https://docs.perplexity.ai/api-reference/agent-post

Defines the available tools that the model can utilize, such as web search, finance search, or function calls.

```APIDOC
## Tool

### Description

Represents a tool that can be used by the model.

### Discriminator

The `type` field determines the specific tool. Possible tool types include:
- `fetch_url`: `FetchUrlTool`
- `finance_search`: `FinanceSearchTool`
- `function`: `FunctionTool`
- `people_search`: `PeopleSearchTool`
- `sandbox`: `SandboxTool`
- `web_search`: `WebSearchTool`

### One Of

This can be one of the following tool types.
```

--------------------------------

### Get Async Chat Completion Response

Source: https://docs.perplexity.ai/api-reference/async-sonar-api-request-get

Retrieves the status and result of an asynchronous chat completion request. The `api_request` parameter is the ID of the asynchronous request.

```APIDOC
## GET /v1/async/sonar/{api_request}

### Description
Retrieve the response for a given asynchronous chat completion request.

### Method
GET

### Endpoint
/v1/async/sonar/{api_request}

### Parameters
#### Path Parameters
- **api_request** (string) - Required - The unique identifier for the asynchronous request.

### Responses
#### Success Response (200)
- **id** (string) - Unique identifier for the async request
- **model** (string) - Model used for the request
- **created_at** (integer) - Unix timestamp when the request was created
- **started_at** (integer or null) - Unix timestamp when processing started
- **completed_at** (integer or null) - Unix timestamp when processing completed
- **response** (object or null) - The completion response object or null if not yet completed
- **failed_at** (integer or null) - Unix timestamp when the request failed (if applicable)
- **error_message** (string or null) - Error message if the request failed
- **status** (object) - Current processing status of the request

#### Error Response (422)
- **detail** (array) - Validation error details
```

--------------------------------

### List Models

Source: https://docs.perplexity.ai/api-reference/models-get

Lists the models available for the Agent API. The response includes model identifiers that can be used with the `POST /v1/agent` endpoint and follows the OpenAI List Models format.

```APIDOC
## GET /v1/models

### Description
Lists the models available for the Agent API. Returns model identifiers that can be used with the `POST /v1/agent` endpoint. The response follows the OpenAI List Models format for compatibility with third-party tools.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **object** (string) - The object type, which is always `list`.
- **data** (array) - A list of model objects.
  - **id** (string) - The model identifier in `provider/model-name` format. Use this value as the `model` parameter in Agent API requests.
  - **object** (string) - The object type, which is always `model`.
  - **created** (integer) - The Unix timestamp (in seconds) when the model was created.
  - **owned_by** (string) - The provider that owns the model (e.g. `openai`, `anthropic`, `google`, `perplexity`, `xai`, `nvidia`).

### Response Example
{
  "object": "list",
  "data": [
    {
      "id": "anthropic/claude-opus-4-8",
      "object": "model",
      "created": 0,
      "owned_by": "anthropic"
    },
    {
      "id": "anthropic/claude-sonnet-4-6",
      "object": "model",
      "created": 0,
      "owned_by": "anthropic"
    },
    {
      "id": "openai/gpt-5.5",
      "object": "model",
      "created": 0,
      "owned_by": "openai"
    },
    {
      "id": "google/gemini-3.1-flash-lite",
      "object": "model",
      "created": 0,
      "owned_by": "google"
    },
    {
      "id": "google/gemini-3.1-flash-lite-preview",
      "object": "model",
      "created": 0,
      "owned_by": "google"
    },
    {
      "id": "google/gemini-3.5-flash",
      "object": "model",
      "created": 0,
      "owned_by": "google"
    },
    {
      "id": "xai/grok-4.3",
      "object": "model",
      "created": 0,
      "owned_by": "xai"
    },
    {
      "id": "xai/grok-4.20-reasoning",
      "object": "model",
      "created": 0,
      "owned_by": "xai"
    },
    {
      "id": "xai/grok-4.20-non-reasoning",
      "object": "model",
      "created": 0,
      "owned_by": "xai"
    },
    {
      "id": "xai/grok-4.20-multi-agent",
      "object": "model",
      "created": 0,
      "owned_by": "xai"
    },
    {
      "id": "perplexity/sonar",
      "object": "model",
      "created": 0,
      "owned_by": "perplexity"
    }
  ]
}
```

--------------------------------

### Direct API Call to Search

Source: https://docs.perplexity.ai/api-reference/search-post

Use this cURL command to directly query the Perplexity AI search API. Ensure your API key is set as an environment variable.

```bash
curl -X POST 'https://api.perplexity.ai/search' \
  -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "latest AI developments",
    "max_results": 3
  }' | jq
```

--------------------------------

### Search the Web

Source: https://docs.perplexity.ai/api-reference/search-post

Search the web and retrieve relevant web page contents. This endpoint allows you to query for information and get back a list of results with associated content.

```APIDOC
## POST /search

### Description
Search the web and retrieve relevant web page contents.

### Method
POST

### Endpoint
/search

### Parameters
#### Query Parameters
- **country** (string) - Optional - ISO 3166-1 alpha-2 country code
- **max_results** (integer) - Optional - Maximum number of results to return (default: 10, max: 20)
- **search_context_size** (string) - Optional - Controls how much content is extracted from result pages. Possible values: `low`, `medium`, `high` (default: `high`)

#### Request Body
- **query** (string) - Required - The search query string.

### Request Example
```json
{
  "query": "latest AI developments",
  "max_results": 3
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results.
  - **title** (string) - The title of the search result.
  - **url** (string) - The URL of the search result.
  - **snippet** (string) - A short snippet of the content from the search result.
  - **content** (string) - The extracted content from the search result.

#### Response Example
```json
{
  "results": [
    {
      "title": "Example AI Development",
      "url": "https://example.com/ai-dev",
      "snippet": "This is a snippet of the latest AI development.",
      "content": "Detailed content about the AI development..."
    }
  ]
}
```

#### Error Response (422)
- **detail** (array) - Details about the validation error.
  - **loc** (array) - The location of the error in the request.
  - **msg** (string) - The error message.
  - **type** (string) - The error type.
```

--------------------------------

### List Async Chat Completions

Source: https://docs.perplexity.ai/api-reference/async-sonar-get

Retrieve a list of all asynchronous chat completion requests for a given user. This endpoint returns a paginated list of requests, with a `next_token` for fetching subsequent pages.

```APIDOC
## GET /v1/async/sonar

### Description
Retrieve a list of all asynchronous chat completion requests for a given user.

### Method
GET

### Endpoint
/v1/async/sonar

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of requests to return per page. Defaults to 20.
- **offset** (integer) - Optional - Number of requests to skip before starting to collect the result set.
- **next_token** (string) - Optional - Token returned from a previous request to retrieve the next page of results.

### Response
#### Success Response (200)
- **next_token** (string or null) - A token to retrieve the next page of results. Null if there are no more pages.
- **requests** (array) - A list of asynchronous chat completion request summaries.
  - **id** (string) - The unique identifier for the request.
  - **created_at** (integer) - The timestamp when the request was created.
  - **started_at** (integer or null) - The timestamp when the request processing started.
  - **completed_at** (integer or null) - The timestamp when the request processing was completed.
  - **failed_at** (integer or null) - The timestamp when the request processing failed.
  - **model** (string) - The model used for the chat completion.
  - **status** (string) - The current status of the asynchronous processing (e.g., CREATED, IN_PROGRESS, COMPLETED, FAILED).

#### Error Response (422)
- **detail** (array) - A list of validation errors.
  - **loc** (array) - The location of the error in the request.
  - **msg** (string) - The error message.
  - **type** (string) - The error type.
```

--------------------------------

### ReasoningConfig

Source: https://docs.perplexity.ai/api-reference/agent-post

Configuration for the reasoning process, allowing control over the effort the model expends.

```APIDOC
## ReasoningConfig

### Description

Configuration for the reasoning process.

### Properties

- **effort** (string) - Optional - How much effort the model should spend on reasoning. Possible values: `low`, `medium`, `high`, `xhigh`, `max`.
```

--------------------------------

### Create Agent Response

Source: https://docs.perplexity.ai/api-reference/agent-post

Generates a response for the provided input with optional web search and reasoning. The response format can be either a JSON object or a Server-Sent Events (SSE) stream.

```APIDOC
## POST /v1/agent

### Description
Generate a response for the provided input with optional web search and reasoning. The response format can be either a JSON object or a Server-Sent Events (SSE) stream, depending on the `stream` parameter.

### Method
POST

### Endpoint
https://api.perplexity.ai/v1/agent

### Parameters
#### Request Body
- **input** (Input) - Required - The user's input to the agent.
- **instructions** (string) - Optional - System instructions for the model.
- **language_preference** (string) - Optional - ISO 639-1 language code for the response language.
- **max_output_tokens** (integer) - Optional - Maximum tokens to generate. Must be at least 1.
- **max_steps** (integer) - Optional - Maximum number of research loop steps. Must be between 1 and 10.
- **model** (string) - Optional - Model ID in provider/model format (e.g., "openai/gpt-5"). Required if neither `models` nor `preset` is provided.
- **models** (array of strings) - Optional - Model fallback chain. Each model is in provider/model format. Max 5 models allowed. Takes precedence over the single `model` field.
- **preset** (string) - Optional - Preset configuration name (e.g., "fast-search", "pro-search"). Required if `model` is not provided.
- **reasoning** (ReasoningConfig) - Optional - Configuration for reasoning.
- **response_format** (ResponseFormat) - Optional - Configuration for the response format.
- **stream** (boolean) - Optional - If true, returns SSE stream instead of JSON.
- **tools** (array of Tool) - Optional - Tools available to the model.

### Request Example
```json
{
  "input": {
    "text": "What is the weather like in London today?"
  },
  "model": "openai/gpt-4o",
  "stream": false
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the response.
- **object** (ResponsesObjectType) - Object type identifier.
- **created_at** (integer) - Unix timestamp when the response was created.
- **model** (string) - Model used for generation.
- **output** (array of OutputItem) - Array of output items (messages, search results, tool calls).
- **usage** (ResponsesUsage) - Token usage and cost information.
- **status** (Status) - Status of the response.
- **error** (ErrorInfo) - Error details if the response failed.

#### Response Example (stream: false)
```json
{
  "id": "resp_abc123",
  "object": "chat.completion",
  "created_at": 1678886400,
  "model": "openai/gpt-4o",
  "output": [
    {
      "type": "message",
      "content": "The weather in London today is partly cloudy with a high of 15 degrees Celsius."
    }
  ],
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 30,
    "total_tokens": 80
  },
  "status": "complete"
}
```

#### Response Example (stream: true)
```
Event: message
data: {"type": "message", "content": "The weather in London today is partly cloudy with a high of 15 degrees Celsius."}

Event: done
data: {}
```
```

--------------------------------

### FunctionTool Configuration

Source: https://docs.perplexity.ai/api-reference/agent-post

Configuration for a FunctionTool, which allows the agent to call external functions. It requires a name and a description of the function's purpose.

```APIDOC
## FunctionTool

### Description
Configuration for a FunctionTool, which allows the agent to call external functions. It requires a name and a description of the function's purpose.

### Properties
- **type** (string) - Required - Must be 'function'.
- **name** (string) - Required - The name of the function to call.
- **description** (string) - Optional - A description of what the function does.
```

--------------------------------

### Input

Source: https://docs.perplexity.ai/api-reference/agent-post

Represents the input content provided to the model. It can be either a single string or an array of input items.

```APIDOC
## Input

### Description

Input content - either a string or array of input items.

### One Of

- **StringInput**: A single string as input.
- **InputItemArray**: An array of `InputItem` objects.
```

--------------------------------

### WebSearchTool

Source: https://docs.perplexity.ai/api-reference/agent-post

Configuration for the Web Search tool, including filters, token limits, and user location.

```APIDOC
## WebSearchTool

### Description
Web search tool configuration for the Responses API.

### Properties
- **type** (string) - Required - Must be 'web_search'.
- **filters** (object) - Optional - Domain and date filters for search results. (Refer to `WebSearchFilters` schema).
- **max_tokens** (integer) - Optional - Maximum total tokens for search context.
- **max_tokens_per_page** (integer) - Optional - Maximum tokens to extract per search result page.
- **user_location** (object) - Optional - User's location for search personalization. (Refer to `ToolUserLocation` schema).
```

--------------------------------

### FunctionTool

Source: https://docs.perplexity.ai/api-reference/agent-post

Configuration for a function tool, used for defining callable functions within the Agent API.

```APIDOC
## FunctionTool

### Description
Defines a tool that can execute a function. It includes the function's name, a JSON schema for its parameters, and an option for strict schema validation.

### Properties
- **type** (string) - Required - Must be 'function'.
- **name** (string) - Required - The name of the function.
- **parameters** (object) - Required - JSON Schema defining the function's parameters.
- **strict** (boolean) - Optional - Whether to enable strict schema validation.
```

--------------------------------

### ApiChatCompletionsRequest Parameters

Source: https://docs.perplexity.ai/api-reference/sonar-post

This section details the parameters available for the chat completions request, allowing for fine-grained control over search, content generation, and response formatting.

```APIDOC
## ApiChatCompletionsRequest Parameters

### Description
Parameters to control search behavior, content filtering, and response generation for chat completions.

### Parameters
#### Request Body Parameters
- **model** (string) - Required - The model to use for generating completions.
- **messages** (array) - Required - An array of message objects representing the conversation history.
- **disable_search** (boolean) - Optional - When true, disables all web search capabilities. The model responds based solely on its training data.
- **search_domain_filter** (array of strings) - Optional - Limit search results to specific domains (e.g. github.com, wikipedia.org).
- **search_language_filter** (array of strings) - Optional - Filter results by language using ISO 639-1 codes (e.g. en, fr, de).
- **search_recency_filter** (string) - Optional - Filter by publication recency (hour, day, week, month, or year).
- **search_after_date_filter** (string) - Optional - Return results published after this date (MM/DD/YYYY).
- **search_before_date_filter** (string) - Optional - Return results published before this date (MM/DD/YYYY).
- **last_updated_before_filter** (string) - Optional - Return results last updated before this date (MM/DD/YYYY).
- **last_updated_after_filter** (string) - Optional - Return results last updated after this date (MM/DD/YYYY).
- **image_format_filter** (array of strings) - Optional - Filter image results by format (e.g. png, jpg).
- **image_domain_filter** (array of strings) - Optional - Limit image results to specific domains.
- **stream_mode** (string) - Optional - Controls the format of streaming events. 'full' suppresses reasoning events and includes metadata inline; 'concise' emits reasoning events separately. Defaults to 'full'.
- **reasoning_effort** (string) - Optional - Controls how much effort the model spends on reasoning (minimal, low, medium, high).
- **language_preference** (string) - Optional - ISO 639-1 language code for preferred response language.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the completion.
- **model** (string) - Model used for generation.
- **created** (integer) - Unix timestamp when the completion was created.
- **usage** (object) - Information about token usage.
- **object** (string) - Object type identifier, defaults to 'chat.completion'.
- **choices** (array) - Array of completion choices.
- **citations** (array of strings) - URLs of sources used to generate the response.
- **search_results** (array) - Results from any searches performed.
```

--------------------------------

### SandboxTool

Source: https://docs.perplexity.ai/api-reference/agent-post

Configuration for the Sandbox tool, which executes code in an isolated container.

```APIDOC
## SandboxTool

### Description
Sandbox tool configuration for the Responses API. Executes code in an isolated container during an Agent API request.

### Properties
- **type** (string) - Required - Must be 'sandbox'.
```

--------------------------------

### FetchUrlResultsOutputItem

Source: https://docs.perplexity.ai/api-reference/agent-post

Represents the output item when the fetch_url_results tool is used.

```APIDOC
## FetchUrlResultsOutputItem

### Description
Output item representing the results of fetching URL content.

### Properties
- **type** (string) - Required - Must be 'fetch_url_results'.
- **contents** (array) - Required - An array of fetched URL content items. (Refer to `UrlContent` schema).
```
Tokens:
Raw