---
title: "Create a batch (Phase 1)"
method: POST
path: "/api/v3/batches"
tags: ["Batches"]
---

# Create a batch (Phase 1)

`POST /api/v3/batches`

Phase 1 of 2-phase batch API. Creates a batch record and optionally blocks the parent run for batchTriggerAndWait.
After creating a batch, stream items via POST /api/v3/batches/{batchId}/items.

## Request body

- CreateBatchRequest
  - `runCount` integer, required — Expected number of items in the batch. Must be a positive integer.
  - `parentRunId` string — Parent run ID (friendly ID) for batchTriggerAndWait.
  - `resumeParentOnCompletion` boolean — Whether to resume parent on completion. Set to true for batchTriggerAndWait.
  - `idempotencyKey` string — Idempotency key for the batch. If provided and a batch with this key already exists, the existing batch will be returned.

## Response `202`

Batch successfully created

- CreateBatchResponse
  - `id` string, required — The batch ID (friendly ID). Use this to stream items via POST /api/v3/batches/{batchId}/items.
  - `runCount` integer, required — The expected run count.
  - `isCached` boolean, required — Whether this response came from a cached/idempotent batch.
  - `idempotencyKey` string — The idempotency key if provided.

## Other responses

- `400` — Invalid request (e.g., runCount <= 0 or exceeds maximum)
- `401` — Unauthorized - API key is missing or invalid
- `422` — Validation error
- `429` — Rate limit exceeded
- `500` — Internal server error

---

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