> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tacetai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a batch

> Start a job from a JSONL file with one record per line. See the batch guide for the file format.



## OpenAPI

````yaml /openapi.yaml post /v1/batches
openapi: 3.1.0
info:
  title: Tacet API
  version: 2026-10
  description: |
    Send a state and typed questions; get calibrated probabilities back as JSON.
    Every answer is one of the options you listed, with a probability for each.
servers:
  - url: https://api.tacetai.com
security:
  - bearerAuth: []
tags:
  - name: Decide
    description: Answer questions about one state, synchronously.
  - name: Batches
    description: >-
      Answer the same questions for a large JSONL file of records,
      asynchronously.
paths:
  /v1/batches:
    post:
      tags:
        - Batches
      summary: Create a batch
      description: >-
        Start a job from a JSONL file with one record per line. See the batch
        guide for the file format.
      operationId: createBatch
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - model
                - file
              properties:
                model:
                  $ref: '#/components/schemas/ModelId'
                file:
                  type: string
                  format: binary
                  description: >-
                    JSONL file. Each line has `custom_id`, `state` and
                    `questions`.
      responses:
        '200':
          description: The new job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        '400':
          $ref: '#/components/responses/InvalidQuestion'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
        - lang: python
          label: Python
          source: >
            job = client.batches.create(model="tacet-alpha",
            input_file="tickets.jsonl")

            print(job.id, job.status)
        - lang: typescript
          label: TypeScript
          source: |
            import fs from "node:fs";

            const job = await client.batches.create({
              model: "tacet-alpha",
              inputFile: fs.createReadStream("tickets.jsonl"),
            });
            console.log(job.id, job.status);
        - lang: bash
          label: curl
          source: |
            curl https://api.tacetai.com/v1/batches \
              -H "Authorization: Bearer $TACET_API_KEY" \
              -F model=tacet-alpha \
              -F file=@tickets.jsonl
components:
  schemas:
    ModelId:
      type: string
      description: >-
        Model id. Use `tacet-alpha` for the latest, or a dated id such as
        `tacet-alpha-2026-10` to pin it.
      example: tacet-alpha
    Batch:
      type: object
      required:
        - id
        - model
        - status
        - progress
        - created_at
      properties:
        id:
          type: string
          example: batch_3k9x2m
        model:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
            - cancelling
            - cancelled
        progress:
          type: object
          properties:
            total:
              type: integer
            completed:
              type: integer
            failed:
              type: integer
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - invalid_question
            - invalid_key
            - state_too_long
            - rate_limited
            - not_found
            - server_error
        message:
          type: string
  responses:
    InvalidQuestion:
      description: >-
        `invalid_question`: check the type and that criteria has 2 to 26
        options.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidKey:
      description: '`invalid_key`: check the Authorization header.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: '`rate_limited`: wait for the time in the Retry-After header, then retry.'
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: '`server_error`: retry with backoff. Contact us if it continues.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Create a key in the Tacet console. Keep it on your server; never ship it
        in a browser or app.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.