openapi: 3.0.1
info:
  title: GroqCloud Audio Batch API
  description: Specification of the Groq cloud API
  termsOfService: https://groq.com/terms-of-use/
  contact:
    name: Groq Support
    email: support@groq.com
  version: '2.1'
servers:
- url: https://api.groq.com
security:
- api_key: []
tags:
- name: Batch
paths:
  /openai/v1/batches:
    post:
      summary: Creates and executes a batch from an uploaded file of requests. [Learn more](/docs/batch).
      operationId: createBatch
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - input_file_id
              - endpoint
              - completion_window
              properties:
                input_file_id:
                  type: string
                  description: 'The ID of an uploaded file that contains requests for the new batch.


                    See [upload file](/docs/api-reference#files-upload) for how to upload a file.


                    Your input file must be formatted as a [JSONL file](/docs/batch), and must be uploaded with the purpose `batch`. The file can be up to 100 MB in size.

                    '
                endpoint:
                  type: string
                  enum:
                  - /v1/chat/completions
                  description: The endpoint to be used for all requests in the batch. Currently `/v1/chat/completions` is supported.
                completion_window:
                  type: string
                  description: The time frame within which the batch should be processed. Durations from `24h` to `7d` are supported.
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: Optional custom metadata for the batch.
                  nullable: true
      responses:
        '200':
          description: Batch created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
      x-groq-metadata:
        returns: A created batch object.
        examples:
        - title: Default
          request:
            curl: "curl https://api.groq.com/openai/v1/batches \\\n  -H \"Authorization: Bearer $GROQ_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"input_file_id\": \"file_01jh6x76wtemjr74t1fh0faj5t\",\n    \"endpoint\": \"/v1/chat/completions\",\n    \"completion_window\": \"24h\"\n  }'\n"
            py: "import os\nfrom groq import Groq\n\nclient = Groq(\n    api_key=os.environ.get(\"GROQ_API_KEY\"),  # This is the default and can be omitted\n)\nbatch = client.batches.create(\n    completion_window=\"24h\",\n    endpoint=\"/v1/chat/completions\",\n    input_file_id=\"file_01jh6x76wtemjr74t1fh0faj5t\",\n)\nprint(batch.id)\n"
            js: "import Groq from 'groq-sdk';\n\nconst client = new Groq({\n  apiKey: process.env['GROQ_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const batch = await client.batches.create({\n    completion_window: \"24h\",\n    endpoint: \"/v1/chat/completions\",\n    input_file_id: \"file_01jh6x76wtemjr74t1fh0faj5t\",\n  });\n  console.log(batch.id);\n}\n\nmain();\n"
          response: "{\n  \"id\": \"batch_01jh6xa7reempvjyh6n3yst2zw\",\n  \"object\": \"batch\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"errors\": null,\n  \"input_file_id\": \"file_01jh6x76wtemjr74t1fh0faj5t\",\n  \"completion_window\": \"24h\",\n  \"status\": \"validating\",\n  \"output_file_id\": null,\n  \"error_file_id\": null,\n  \"finalizing_at\": null,\n  \"failed_at\": null,\n  \"expired_at\": null,\n  \"cancelled_at\": null,\n  \"request_counts\": {\n    \"total\": 0,\n    \"completed\": 0,\n    \"failed\": 0\n  },\n  \"metadata\": null,\n  \"created_at\": 1736472600,\n  \"expires_at\": 1736559000,\n  \"cancelling_at\": null,\n  \"completed_at\": null,\n  \"in_progress_at\": null\n}\n"
    get:
      operationId: listBatches
      tags:
      - Batch
      summary: List your organization's batches.
      responses:
        '200':
          description: Batch listed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBatchesResponse'
      x-groq-metadata:
        returns: A list of batches
        examples:
        - title: Default
          request:
            curl: "curl https://api.groq.com/openai/v1/batches \\\n  -H \"Authorization: Bearer $GROQ_API_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
            py: "import os\nfrom groq import Groq\n\nclient = Groq(\n    api_key=os.environ.get(\"GROQ_API_KEY\"),  # This is the default and can be omitted\n)\nbatch_list = client.batches.list()\nprint(batch_list.data)\n"
            js: "import Groq from 'groq-sdk';\n\nconst client = new Groq({\n  apiKey: process.env['GROQ_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const batchList = await client.batches.list();\n  console.log(batchList.data);\n}\n\nmain();\n"
          response: "{\n  \"object\": \"list\",\n  \"data\": [\n    {\n      \"id\": \"batch_01jh6xa7reempvjyh6n3yst2zw\",\n      \"object\": \"batch\",\n      \"endpoint\": \"/v1/chat/completions\",\n      \"errors\": null,\n      \"input_file_id\": \"file_01jh6x76wtemjr74t1fh0faj5t\",\n      \"completion_window\": \"24h\",\n      \"status\": \"validating\",\n      \"output_file_id\": null,\n      \"error_file_id\": null,\n      \"finalizing_at\": null,\n      \"failed_at\": null,\n      \"expired_at\": null,\n      \"cancelled_at\": null,\n      \"request_counts\": {\n        \"total\": 0,\n        \"completed\": 0,\n        \"failed\": 0\n      },\n      \"metadata\": null,\n      \"created_at\": 1736472600,\n      \"expires_at\": 1736559000,\n      \"cancelling_at\": null,\n      \"completed_at\": null,\n      \"in_progress_at\": null\n    }\n  ]\n}\n"
  /openai/v1/batches/{batch_id}:
    get:
      operationId: retrieveBatch
      tags:
      - Batch
      summary: Retrieves a batch.
      parameters:
      - in: path
        name: batch_id
        required: true
        schema:
          type: string
        description: The ID of the batch to retrieve.
      responses:
        '200':
          description: Batch retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
      x-groq-metadata:
        returns: A batch object.
        examples:
        - title: Default
          request:
            curl: "curl https://api.groq.com/openai/v1/batches/batch_01jh6xa7reempvjyh6n3yst2zw \\\n  -H \"Authorization: Bearer $GROQ_API_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
            py: "import os\nfrom groq import Groq\n\nclient = Groq(\n    api_key=os.environ.get(\"GROQ_API_KEY\"),  # This is the default and can be omitted\n)\nbatch = client.batches.retrieve(\n    \"batch_01jh6xa7reempvjyh6n3yst2zw\",\n)\nprint(batch.id)\n"
            js: "import Groq from 'groq-sdk';\n\nconst client = new Groq({\n  apiKey: process.env['GROQ_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const batch = await client.batches.retrieve(\"batch_01jh6xa7reempvjyh6n3yst2zw\");\n  console.log(batch.id);\n}\n\nmain();\n"
          response: "{\n  \"id\": \"batch_01jh6xa7reempvjyh6n3yst2zw\",\n  \"object\": \"batch\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"errors\": null,\n  \"input_file_id\": \"file_01jh6x76wtemjr74t1fh0faj5t\",\n  \"completion_window\": \"24h\",\n  \"status\": \"validating\",\n  \"output_file_id\": null,\n  \"error_file_id\": null,\n  \"finalizing_at\": null,\n  \"failed_at\": null,\n  \"expired_at\": null,\n  \"cancelled_at\": null,\n  \"request_counts\": {\n    \"total\": 0,\n    \"completed\": 0,\n    \"failed\": 0\n  },\n  \"metadata\": null,\n  \"created_at\": 1736472600,\n  \"expires_at\": 1736559000,\n  \"cancelling_at\": null,\n  \"completed_at\": null,\n  \"in_progress_at\": null\n}\n"
  /openai/v1/batches/{batch_id}/cancel:
    post:
      operationId: cancelBatch
      tags:
      - Batch
      summary: Cancels a batch.
      parameters:
      - in: path
        name: batch_id
        required: true
        schema:
          type: string
        description: The ID of the batch to cancel.
      responses:
        '200':
          description: Batch cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
      x-groq-metadata:
        returns: A batch object.
        examples:
        - title: Default
          request:
            curl: "curl -X POST https://api.groq.com/openai/v1/batches/batch_01jh6xa7reempvjyh6n3yst2zw/cancel \\\n  -H \"Authorization: Bearer $GROQ_API_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
            py: "import os\nfrom groq import Groq\n\nclient = Groq(\n    api_key=os.environ.get(\"GROQ_API_KEY\"),  # This is the default and can be omitted\n)\nbatch = client.batches.cancel(\n    \"batch_01jh6xa7reempvjyh6n3yst2zw\",\n)\nprint(batch.id)\n"
            js: "import Groq from 'groq-sdk';\n\nconst client = new Groq({\n  apiKey: process.env['GROQ_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const batch = await client.batches.cancel(\"batch_01jh6xa7reempvjyh6n3yst2zw\");\n  console.log(batch.id);\n}\n\nmain();\n"
          response: "{\n  \"id\": \"batch_01jh6xa7reempvjyh6n3yst2zw\",\n  \"object\": \"batch\",\n  \"endpoint\": \"/v1/chat/completions\",\n  \"errors\": null,\n  \"input_file_id\": \"file_01jh6x76wtemjr74t1fh0faj5t\",\n  \"completion_window\": \"24h\",\n  \"status\": \"cancelling\",\n  \"output_file_id\": null,\n  \"error_file_id\": null,\n  \"finalizing_at\": null,\n  \"failed_at\": null,\n  \"expired_at\": null,\n  \"cancelled_at\": null,\n  \"request_counts\": {\n    \"total\": 0,\n    \"completed\": 0,\n    \"failed\": 0\n  },\n  \"metadata\": null,\n  \"created_at\": 1736472600,\n  \"expires_at\": 1736559000,\n  \"cancelling_at\": null,\n  \"completed_at\": null,\n  \"in_progress_at\": null\n}\n"
components:
  schemas:
    ListBatchesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Batch'
        object:
          type: string
          enum:
          - list
          x-stainless-const: true
      required:
      - object
      - data
    Batch:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - batch
          description: The object type, which is always `batch`.
          x-stainless-const: true
        endpoint:
          type: string
          description: The API endpoint used by the batch.
        errors:
          type: object
          properties:
            object:
              type: string
              description: The object type, which is always `list`.
            data:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                    description: An error code identifying the error type.
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                  param:
                    type: string
                    description: The name of the parameter that caused the error, if applicable.
                    nullable: true
                  line:
                    type: integer
                    description: The line number of the input file where the error occurred, if applicable.
                    nullable: true
        input_file_id:
          type: string
          description: The ID of the input file for the batch.
        completion_window:
          type: string
          description: The time frame within which the batch should be processed.
        status:
          type: string
          description: The current status of the batch.
          enum:
          - validating
          - failed
          - in_progress
          - finalizing
          - completed
          - expired
          - cancelling
          - cancelled
        output_file_id:
          type: string
          description: The ID of the file containing the outputs of successfully executed requests.
        error_file_id:
          type: string
          description: The ID of the file containing the outputs of requests with errors.
        created_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch was created.
        in_progress_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch started processing.
        expires_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch will expire.
        finalizing_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch started finalizing.
        completed_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch was completed.
        failed_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch failed.
        expired_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch expired.
        cancelling_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch started cancelling.
        cancelled_at:
          type: integer
          description: The Unix timestamp (in seconds) for when the batch was cancelled.
        request_counts:
          type: object
          properties:
            total:
              type: integer
              description: Total number of requests in the batch.
            completed:
              type: integer
              description: Number of requests that have been completed successfully.
            failed:
              type: integer
              description: Number of requests that have failed.
          required:
          - total
          - completed
          - failed
          description: The request counts for different statuses within the batch.
        metadata:
          description: 'Set of key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format.

            '
          type: object
          nullable: true
      required:
      - id
      - object
      - endpoint
      - input_file_id
      - completion_window
      - status
      - created_at
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
x-groq-metadata:
  groups:
  - id: chat
    type: endpoints
    title: Chat
    description: ''
    sections:
    - type: endpoint
      key: createChatCompletion
      path: create
  - id: responses
    type: endpoints
    title: Responses (beta)
    description: ''
    sections:
    - type: endpoint
      key: createResponse
      path: create
  - id: audio
    type: endpoints
    title: Audio
    description: ''
    sections:
    - type: endpoint
      key: createTranscription
      path: transcription
    - type: endpoint
      key: createTranslation
      path: translation
    - type: endpoint
      key: createSpeech
      path: speech
  - id: models
    type: endpoints
    title: Models
    description: ''
    sections:
    - type: endpoint
      key: listModels
      path: list
    - type: endpoint
      key: retrieveModel
      path: retrieve
  - id: batches
    type: endpoints
    title: Batches
    description: ''
    sections:
    - type: endpoint
      key: createBatch
      path: create
    - type: endpoint
      key: retrieveBatch
      path: retrieve
    - type: endpoint
      key: listBatches
      path: list
    - type: endpoint
      key: cancelBatch
      path: cancel
  - id: files
    type: endpoints
    title: Files
    description: ''
    sections:
    - type: endpoint
      key: uploadFile
      path: upload
    - type: endpoint
      key: listFiles
      path: list
    - type: endpoint
      key: deleteFile
      path: delete
    - type: endpoint
      key: retrieveFile
      path: retrieve
    - type: endpoint
      key: downloadFile
      path: download
  - id: fine-tuning
    type: endpoints
    title: Fine Tuning
    description: ''
    sections:
    - type: endpoint
      key: listFineTunings
      path: list
    - type: endpoint
      key: createFineTuning
      path: create
    - type: endpoint
      key: getFineTuning
      path: get
    - type: endpoint
      key: deleteFineTuning
      path: delete