---
title: "Public Create Batch"
method: POST
path: "/v1/batches"
tags: ["public-api"]
---

# Public Create Batch

`POST /v1/batches`

## Request

- Base URL: `https://api.trainloop.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.trainloop.ai/v1/batches`
- Auth: none declared

Submit a batch: every object under ``input_path`` goes through the
pipeline and its outputs land under ``output_path``, mirroring the
input tree. Read and write access are proven now, so the real AWS
error is the response, not a failed batch later.

Send ``Idempotency-Key`` (any string up to 128 chars, unique per
submission) and a retry from anywhere returns the same batch.
Poll ``GET /v1/batches/{id}`` every 15–60 seconds.

## Headers

- `Idempotency-Key` string, nullable
- `authorization` string, nullable

## Request body

- BatchCreate: POST /v1/batches body. ``input_path`` / ``output_path`` are ``s3://bucket/prefix`` reachable through ``connection_id`` (read on input, write on output — both are proven at submit time). ``options`` is validated against the pipeline's own schema (see GET /v1/pipelines).
  - `pipeline` string, required
  - `connection_id` string, uuid, required
  - `input_path` string, required
  - `output_path` string, required
  - `options` object

## Response `201`

Successful Response

- BatchResponse
  - `id` string, uuid, required
  - `pipeline` string, required
  - `status` 'queued' | 'dispatched' | 'running' | 'completed' | 'completed_with_errors' | 'failed' | 'cancelled', required
  - `connection_id` string, uuid, required
  - `input_path` string, required
  - `output_path` string, required
  - `options` object, required
  - `item_total` integer, required
  - `item_done` integer, required
  - `item_skipped` integer, required
  - `item_failed` integer, required
  - `error` string, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `started_at` string, date-time, nullable, required
  - `finished_at` string, date-time, nullable, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-09** `dec6fd242e40`: 2 info
  - api operation id `create_batch_v1_batches_post` removed and replaced with `public_create_batch_v1_batches_post`
  - api tag `batches` removed
- **2026-09-09** `26478f75ef09`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trainloop/apis/trainloop-api/changes/v1/batches/post.md)

---

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