Perplexity Batches API

openapi: 3.2.0
info:
  title: Perplexity AI Batches API
  description: Perplexity AI API
  version: 1.0.0
servers:
- url: https://api.perplexity.ai
  description: Perplexity AI API
tags:
- name: Batches
paths:
  /v1/batches:
    post:
      operationId: createBatch
      summary: Create a batch
      description: 'Creates a batch from an uploaded input file. The batch starts in

        `validating`. Send an `Idempotency-Key` header to make retries safe: a

        repeat with the same key returns the original batch.

        `output_expires_after` is not supported and is rejected with a 400;

        output and error files are kept 30 days.'
      parameters:
      - $ref: '#/components/parameters/BatchIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatchRequest'
      responses:
        '200':
          description: The created batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        '400':
          description: Invalid request, input file, or reused idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: API credits exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Batch is not available to organizations with zero data retention
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Batch service unavailable; retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
    get:
      operationId: listBatches
      summary: List batches
      description: Lists your organization's batches, newest first.
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Maximum number of batches to return
      - name: after_id
        in: query
        required: false
        schema:
          type: string
        description: Batch id to start after, the `last_id` of the previous page
      responses:
        '200':
          description: A page of batches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchList'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
  /v1/batches/{batch_id}:
    get:
      operationId: getBatch
      summary: Retrieve a batch
      parameters:
      - $ref: '#/components/parameters/BatchId'
      responses:
        '200':
          description: The batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        '404':
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
  /v1/batches/{batch_id}/cancel:
    post:
      operationId: cancelBatch
      summary: Cancel a batch
      description: 'Moves the batch to `cancelling`; it becomes `cancelled` once running

        items stop. Completed items stay in the output file and are billed.

        Cancelling a cancelled or cancelling batch returns it unchanged.'
      parameters:
      - $ref: '#/components/parameters/BatchId'
      responses:
        '200':
          description: The batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        '404':
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: The batch is finalizing or already finished
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
  /v1/files:
    get:
      operationId: listFiles
      summary: List files
      description: 'Lists your organization''s files, both uploads and the output and error

        files batches write. Deleted and expired files are not listed.'
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Maximum number of files to return
      - name: after_id
        in: query
        required: false
        schema:
          type: string
        description: File id to start after, the `last_id` of the previous page
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        description: Sort order, `desc` for newest first
      - name: purpose
        in: query
        required: false
        schema:
          type: string
          enum:
          - batch
          - batch_output
        description: Only list files with this purpose, `batch` for uploads or `batch_output` for output and error files
      responses:
        '200':
          description: A page of files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFileList'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
    post:
      operationId: createFile
      summary: Upload a file
      description: 'Uploads a JSONL batch input file, up to 50,000 lines and 200 MB. Every

        line is validated before the file is stored. Files expire after 30 days;

        `expires_after` is not supported and is rejected with a 400.'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - purpose
              properties:
                file:
                  type: string
                  format: binary
                  description: The JSONL file
                purpose:
                  type: string
                  enum:
                  - batch
                  description: Only `batch` is accepted
      responses:
        '200':
          description: The stored file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFile'
        '400':
          description: Invalid request or file contents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Batch is not available to organizations with zero data retention
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '413':
          description: File exceeds 200 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit or upload concurrency limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
  /v1/files/{file_id}:
    get:
      operationId: getFile
      summary: Retrieve a file
      parameters:
      - $ref: '#/components/parameters/BatchFileId'
      responses:
        '200':
          description: The file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFile'
        '404':
          description: File not found or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
    delete:
      operationId: deleteFile
      summary: Delete a file
      description: Deletes a file. Batches already created from it are not affected.
      parameters:
      - $ref: '#/components/parameters/BatchFileId'
      responses:
        '200':
          description: The file was deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFileDeleted'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
  /v1/files/{file_id}/content:
    get:
      operationId: getFileContent
      summary: Download file content
      description: Streams the raw bytes of an input, output, or error file.
      parameters:
      - $ref: '#/components/parameters/BatchFileId'
      responses:
        '200':
          description: The file bytes
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: File not found or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - HTTPBearer: []
      tags:
      - Batches
components:
  parameters:
    BatchIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 200
      description: Unique key for this create; a repeat returns the original batch
    BatchId:
      name: batch_id
      in: path
      required: true
      schema:
        type: string
      description: Batch identifier (batch_...)
    BatchFileId:
      name: file_id
      in: path
      required: true
      schema:
        type: string
      description: File identifier (file_...)
  schemas:
    Batch:
      type: object
      required:
      - id
      - object
      - endpoint
      - input_file_id
      - completion_window
      - status
      - created_at
      - request_counts
      - usage
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - batch
        endpoint:
          type: string
        errors:
          allOf:
          - $ref: '#/components/schemas/BatchErrors'
          nullable: true
        input_file_id:
          type: string
        completion_window:
          type: string
        status:
          $ref: '#/components/schemas/BatchStatus'
        output_file_id:
          type: string
          nullable: true
        error_file_id:
          type: string
          nullable: true
        created_at:
          type: integer
          format: int64
          description: Unix seconds
        in_progress_at:
          type: integer
          format: int64
          nullable: true
        expires_at:
          type: integer
          format: int64
          nullable: true
        finalizing_at:
          type: integer
          format: int64
          nullable: true
        completed_at:
          type: integer
          format: int64
          nullable: true
        failed_at:
          type: integer
          format: int64
          nullable: true
        expired_at:
          type: integer
          format: int64
          nullable: true
        cancelling_at:
          type: integer
          format: int64
          nullable: true
        cancelled_at:
          type: integer
          format: int64
          nullable: true
        request_counts:
          $ref: '#/components/schemas/BatchRequestCounts'
        usage:
          $ref: '#/components/schemas/BatchUsage'
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
    BatchRequestCounts:
      type: object
      required:
      - total
      - completed
      - failed
      properties:
        total:
          type: integer
          format: int64
        completed:
          type: integer
          format: int64
        failed:
          type: integer
          format: int64
    BatchUsage:
      type: object
      required:
      - input_tokens
      - input_tokens_details
      - output_tokens
      - output_tokens_details
      - total_tokens
      properties:
        input_tokens:
          type: integer
          format: int64
        input_tokens_details:
          type: object
          required:
          - cached_tokens
          properties:
            cached_tokens:
              type: integer
              format: int64
        output_tokens:
          type: integer
          format: int64
        output_tokens_details:
          type: object
          required:
          - reasoning_tokens
          properties:
            reasoning_tokens:
              type: integer
              format: int64
        total_tokens:
          type: integer
          format: int64
    BatchList:
      type: object
      required:
      - object
      - data
      - has_more
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Batch'
        first_id:
          type: string
          nullable: true
        last_id:
          type: string
          nullable: true
        has_more:
          type: boolean
    BatchFileList:
      type: object
      required:
      - object
      - data
      - has_more
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/BatchFile'
        first_id:
          type: string
          nullable: true
        last_id:
          type: string
          nullable: true
        has_more:
          type: boolean
    BatchError:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
        message:
          type: string
        line:
          type: integer
          format: int64
          nullable: true
          description: 1-based input line the error refers to
    BatchStatus:
      type: string
      enum:
      - validating
      - in_progress
      - finalizing
      - completed
      - expired
      - cancelling
      - cancelled
      - failed
    BatchFile:
      type: object
      required:
      - id
      - object
      - bytes
      - created_at
      - filename
      - purpose
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - file
        bytes:
          type: integer
          format: int64
        created_at:
          type: integer
          format: int64
          description: Unix seconds
        expires_at:
          type: integer
          format: int64
          nullable: true
          description: Unix seconds
        filename:
          type: string
        purpose:
          type: string
          enum:
          - batch
          - batch_output
          description: '`batch` for uploads, `batch_output` for output and error files'
    CreateBatchRequest:
      type: object
      required:
      - input_file_id
      - endpoint
      properties:
        input_file_id:
          type: string
          description: Id of a file uploaded with `purpose=batch`
        endpoint:
          type: string
          enum:
          - /v1/responses
          description: Endpoint every line in the input file targets
        completion_window:
          type: string
          enum:
          - 24h
          description: Target completion time; `24h` is the only value and the default
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: Up to 16 key value pairs; keys up to 64 characters, values up to 512
    BatchFileDeleted:
      type: object
      required:
      - id
      - object
      - deleted
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - file
        deleted:
          type: boolean
    BatchErrors:
      type: object
      required:
      - object
      - data
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/BatchError'
    ApiError:
      type: object
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable error message
            type:
              type: string
              description: Error type identifier
            code:
              type: integer
              description: HTTP status code
            param:
              type: string
              description: Parameter that caused the error
              nullable: true
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer