---
title: "Submit 1 to plan limit jobs atomically"
method: POST
path: "/v1/batches"
tags: ["batches"]
---

# Submit 1 to plan limit jobs atomically

`POST /v1/batches`

## Request

- Base URL: `https://api.transcriptdock.com`
- URL: `https://api.transcriptdock.com/v1/batches`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `sb-access-token`

## Headers

- `Idempotency-Key` string, required

## Request body

- BatchRequest
  - `items` JobRequest[], required
    - `source` union, required
      - object
        - `url` string, uri, required: YouTube or TikTok video URL (captions_only); any https media URL for direct sources (AI transcription). Exactly one of url or upload_id.
        - `upload_id` string, uuid: Id from POST /v1/uploads after the file was PUT and the upload is ready. Exactly one of url or upload_id.
      - object
        - `url` string, uri: YouTube or TikTok video URL (captions_only); any https media URL for direct sources (AI transcription). Exactly one of url or upload_id.
        - `upload_id` string, uuid, required: Id from POST /v1/uploads after the file was PUT and the upload is ready. Exactly one of url or upload_id.
    - `mode` 'captions_only' | 'auto' | 'transcribe', required
    - `language` string, nullable: Only applies to AI transcription (auto/transcribe).
    - `caption_languages` string[]: BCP 47 tags in preference order for the caption track, e.g. ["en", "es"]. Empty means the video default.
    - `caption_preference` 'prefer_creator' | 'creator_only' | 'automatic_only'
    - `recognition_profile` 'standard': Only applies to AI transcription (auto/transcribe).
    - `max_credits` integer: Optional ceiling in credits for auto/transcribe. AI transcription costs transcribe_credits_per_minute per started minute after minimum_billable_seconds (see GET /v1/capabilities); a job whose measured cost exceeds the ceiling fails with BUDGET_EXCEEDED before any provider spend. Default covers max_duration_ms. Ignored for captions_only.
    - `webhook_endpoint_id` string, uuid, nullable: Endpoint from POST /v1/webhooks that receives job.succeeded / job.failed for this job.
    - `metadata` object
  - `metadata` object
  - `webhook_endpoint_id` string, uuid, nullable

## Response `200`

Same batch idempotency key replayed

- Batch
  - `id` string, uuid, required: Batch id; use with GET /v1/batches/{id}.
  - `status` 'queued' | 'processing' | 'succeeded' | 'partial_success' | 'failed' | 'cancelled', required: Aggregate of the child jobs: partial_success when some succeeded and some failed.
  - `total_items` integer, required: Number of submitted items; duplicate URLs share one child job.
  - `succeeded_items` integer, required: Items whose child job succeeded.
  - `failed_items` integer, required: Items whose child job failed.
  - `cancelled_items` integer, required: Items whose child job was cancelled.
  - `child_job_ids` string[], required: Distinct child job ids, in item order.
  - `items` BatchItem[], required: One entry per submitted item with its job id and status.
    - `job_id` string, uuid, required
    - `item_index` integer, required
    - `status` 'queued' | 'processing' | 'awaiting_provider' | 'succeeded' | 'failed' | 'cancelled', required
  - `created_at` string, date-time, required: Submission time, UTC.

## Other responses

- `202`: Batch accepted; children reserved together or whole batch rejected
- `402`: Reservation refused (balance, budget, plan)
- `422`: Request shape or capability rejected

---

[API](https://skmtc.dev/transcriptdock/apis/transcriptdock-api.md) · [All operations](https://skmtc.dev/transcriptdock/apis/transcriptdock-api/llms.txt) · [OpenAPI document](https://skmtc.dev/transcriptdock/apis/transcriptdock-api/revisions/7bda7594bdfd?raw)