---
title: "Create batch"
method: POST
path: "/batches"
tags: ["batches"]
---

# Create batch

`POST /batches`

Create and start processing a batch from an uploaded file.

The batch will begin processing immediately. Use `GET /batches/{batch_id}` to monitor progress.

## Request body

- CreateBatchRequest — Request body for creating a batch
  - `api_key_id` string, uuid, nullable — Attribute this batch to a specific API key (organization context only). The key must belong to the organization and be usable by the caller: one they created, or any org key for org owners/admins. The batch's spend counts against the selected key's usage limit and its usage is attributed to the key's creator. Members of a managed-keys organization must select a key when creating batches from the dashboard.
  - `completion_window` string, required — The time window within which the batch should be processed (e.g., "24h", "1h"). The provider extension `"background"` selects no-SLA spare-capacity processing and requires the `BackgroundInferenceUser` role. Other allowed values are configured per instance.
  - `endpoint` string, required — The endpoint to be used for all requests in the batch. Supported values are configured via `batches.allowed_url_paths`.
  - `input_file_id` string, required — The ID of an uploaded file that contains requests for the new batch
  - `metadata` object, nullable — Optional metadata (up to 16 key-value pairs)

## Response `201`

Batch created and queued for processing.

- BatchResponse — Batch object response (OpenAI-compatible)
  - `analytics` BatchAnalytics — Aggregated analytics metrics for batch requests
    - `avg_duration_ms` number, double, nullable — Average request duration in milliseconds
    - `avg_ttfb_ms` number, double, nullable — Average time to first byte in milliseconds
    - `total_completion_tokens` integer, required — Total completion tokens across all requests
    - `total_cost` string, nullable — Total BILLED cost in credits (if pricing is available) — what the batch actually cost after prompt-cache discounts, matching the credits ledger / transactions page. (Until 2026-07 this field erroneously reported the un-discounted list price; see `total_list_cost` for that figure.)
    - `total_list_cost` string, nullable — Un-discounted list price of the same requests (no prompt-cache discounts applied). `total_list_cost - total_cost` = what caching saved on this batch. Additive field — clients that don't know it simply ignore it.
    - `total_prompt_tokens` integer, required — Total prompt tokens across all requests
    - `total_reasoning_tokens` integer, nullable — Total reasoning tokens across all requests
    - `total_requests` integer, required — Total number of requests with analytics data
    - `total_tokens` integer, required — Total tokens (prompt + completion) across all requests
  - `cancelled_at` integer, nullable
  - `cancelling_at` integer, nullable
  - `completed_at` integer, nullable
  - `completion_window` string, required — The requested processing window, or `"background"` for no-SLA spare-capacity processing.
  - `created_at` integer, required
  - `dwext` BatchDwExtResponse — Doubleword extension fields on batch responses. Returned as `"dwext": { ... }` at the top level of batch objects. Only present when there is Doubleword-specific data to surface.
    - `source` string, nullable — How the batch was created: "api", "frontend", or "sync".
    - `source_file` string, nullable — Original external file key (when source = "sync").
    - `source_id` string, nullable — Source connection ID (when source = "sync").
    - `source_name` string, nullable — Name of the source connection (when source = "sync").
    - `sync_id` string, nullable — Sync operation ID that created this batch (when source = "sync").
  - `endpoint` string, required
  - `error_file_id` string, nullable
  - `errors` BatchErrors — Batch-level errors
    - `data` BatchError[], required — Array of error details
      - `code` string, nullable — An error code identifying the error type
      - `line` integer, nullable — The line number of the input file where the error occurred, if applicable
      - `message` string, required — A human-readable message providing more details about the error
      - `param` string, nullable — The name of the parameter that caused the error, if applicable
  - `expired_at` integer, nullable
  - `expires_at` integer, nullable
  - `failed_at` integer, nullable
  - `finalizing_at` integer, nullable
  - `id` string, required
  - `in_progress_at` integer, nullable
  - `input_file_id` string, required
  - `metadata` object, nullable
  - `model` string, nullable — Model alias used by this batch's requests, or `"mixed"` when the input file spans multiple models. Cached on the batch at creation time; absent on batches created before this field existed.
  - `object` 'batch', required — Object type - always "batch"
  - `output_file_id` string, nullable
  - `request_counts` RequestCounts, required — Request counts for a batch
    - `completed` integer, required
    - `failed` integer, required
    - `total` integer, required
  - `status` string, required

## Other responses

- `400` — Invalid request — check that the endpoint and completion_window are valid.
- `402` — Insufficient credits — account balance is below zero.
- `404` — Input file not found or you don't have access to it.
- `422` — A reasoning effort maps to an absolute token budget but the request does not provide a sufficient output-token limit.
- `500` — An unexpected error occurred. Retry the request or contact support if the issue persists.

---

[API](https://skmtc.dev/doubleword/apis/doubleword-api.md) · [All operations](https://skmtc.dev/doubleword/apis/doubleword-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/doubleword/doubleword-api/revisions/6617202865d8/schema)