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

# Submit batch transcription

> Submit a batch for transcription using a completed batch_upload_id, specific file_ids from prior uploads, and/or an explicit sources list with gcs_key or url per item.

Submit a batch of audio for transcription. Accepts a JSON body with:

* `batch_upload_id` (optional): include all completed files from one upload request
* `file_ids` (optional): list of specific `file_id` strings from prior `POST /files/upload` responses
* `sources` (optional): explicit list of GCS keys or URLs

At least one of `batch_upload_id`, `file_ids`, or `sources` must resolve to at least one file. All fields can be combined in a single request.

Each source item must include either `gcs_key` or `url`, and may include an optional `filename`.

Uploaded files referenced by `batch_upload_id` or `file_ids` must have `upload_status: "completed"`. If uploads are still in progress, the API returns `409`.

When a file is selected via `file_ids`, the same `file_id` from the upload response is reused for transcription results.

## Example (from completed upload)

```bash theme={"system"}
curl -X POST "https://api.soket.ai/transcribe/batch" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_upload_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
```

## Example (specific file\_ids)

```bash theme={"system"}
curl -X POST "https://api.soket.ai/transcribe/batch" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_ids": [
      "1374132b-b5db-4ec3-9cf1-f61f982e89b0",
      "2485243c-c6ec-5fd4-0dg2-g72g093f90c1"
    ]
  }'
```

## Example (upload batch + specific files + URLs)

```bash theme={"system"}
curl -X POST "https://api.soket.ai/transcribe/batch" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_upload_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "file_ids": ["3596354d-d7fd-6ge5-1eh3-h83h104g01d2"],
    "sources": [
      {"url": "https://example.com/audio3.wav", "filename": "audio3.wav"}
    ]
  }'
```

## Typical response

```json theme={"system"}
{
  "batch_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "total_jobs": 3,
  "estimated_audio_seconds": 290.0,
  "estimated_completion_seconds": 21.7,
  "jobs": [
    {
      "file_id": "1374132b-b5db-4ec3-9cf1-f61f982e89b0",
      "filename": "audio1.wav",
      "batch_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "status": "queued"
    }
  ]
}
```


## OpenAPI

````yaml POST /batch
openapi: 3.0.3
info:
  title: Dhrith ASR API
  version: 1.0.0
  description: >-
    Upload audio, submit batches, track progress, and fetch merged transcription
    results.
servers:
  - url: https://api.soket.ai/transcribe
    description: Batch transcription, status, results, and download
  - url: https://api.soket.ai
    description: File upload and management
security:
  - bearerAuth: []
paths:
  /batch:
    post:
      summary: Submit batch transcription
      description: >-
        Submit a batch for transcription using a completed batch_upload_id,
        specific file_ids from prior uploads, and/or an explicit sources list
        with gcs_key or url per item.
      operationId: submitBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch accepted and enqueued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSubmitResponse'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Upload batch belongs to a different user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: batch_upload_id or file_ids not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Uploads still in progress or file_ids not yet completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Queue full
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BatchRequest:
      type: object
      properties:
        batch_upload_id:
          type: string
          description: Include all completed files from this POST /files/upload response
        file_ids:
          type: array
          items:
            type: string
          description: >-
            Specific file_id values from POST /files/upload; can span multiple
            upload batches
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceItem'
          description: Explicit GCS keys or URLs; each item must have gcs_key or url
    BatchSubmitResponse:
      type: object
      properties:
        batch_id:
          type: string
        total_jobs:
          type: integer
        estimated_audio_seconds:
          type: number
        estimated_completion_seconds:
          type: number
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/BatchJob'
    ErrorResponse:
      type: object
      properties:
        detail:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
    SourceItem:
      type: object
      properties:
        gcs_key:
          type: string
        url:
          type: string
        filename:
          type: string
    BatchJob:
      type: object
      properties:
        file_id:
          type: string
        filename:
          type: string
        batch_id:
          type: string
        status:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````