---
title: "Create an analysis batch"
method: POST
path: "/api/v1/analysis-batches"
tags: ["Batches"]
---

# Create an analysis batch

`POST /api/v1/analysis-batches`

## Request

- Base URL: `https://app.probbai.com`
- URL: `https://app.probbai.com/api/v1/analysis-batches`
- Auth: HTTP bearer

Queue several analyses in one durable request and track outcomes by your own itemKey. Use this to process an application import without coordinating every admission yourself.

## Before you call

Supply 1–20 items, at most 256 KiB JSON, unique itemKey values, and an Idempotency-Key. Only one batch of each kind can be active per workspace.

**Required scope:** `analyses:write`.

## What happens next

A 202 returns batchId and statusUrl. Items can succeed or fail independently. Items finish only after their admitted analysis reaches a terminal outcome. Fetch each report to distinguish completed, failed, and requires_action.

## Recovery

Keep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.

[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)

## Headers

- `Idempotency-Key` string, required

## Request body

- AnalysisBatchInput
  - `items` object[], required: Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next.
    - `itemKey` string, required: Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key.
    - `input` object, required: The request for this individual batch item, using the corresponding single-operation fields.
      - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
      - `quoteFingerprint` string, required: Fingerprint copied unchanged from the corresponding current quote. Changing quote inputs requires a new quote.

## Response `202`

A 202 returns batchId and statusUrl. Items can succeed or fail independently. Items finish only after their admitted analysis reaches a terminal outcome. Fetch each report to distinguish completed, failed, and requires_action.

- object
  - `data` BatchAdmission, required
    - `batchId` string, required: Identifier returned when the batch was accepted; use it to retrieve item outcomes.
    - `statusUrl` string, required: Relative API path to poll with the same workspace API key. Resolve against your application origin.

## Other responses

- `400`: Invalid input or cursor
- `401`: Invalid, expired, or revoked API key
- `403`: Disabled organisation or missing scope
- `404`: The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.
- `405`: Method not allowed; consult Allow for supported methods
- `409`: Keep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.
- `429`: Request limit exceeded
- `500`: Unexpected failure
- `503`: Service unavailable

---

[API](https://skmtc.dev/probbai/apis/probb-ai-customer-api.md) · [All operations](https://skmtc.dev/probbai/apis/probb-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/probbai/apis/probb-ai-customer-api/revisions/33a3294530e4?raw)