---
title: "Upload an async batch"
method: POST
path: "/v1/reflex/asynchronous_batches/upload"
tags: ["reflex"]
---

# Upload an async batch

`POST /v1/reflex/asynchronous_batches/upload`

Queue up to 10,000 rows for offline classification at the discounted batch rate. Returns immediately with a `batch_id` once the rows are queued — it does not wait for classification. `model` must be an array here, even for one model. Pass an `Idempotency-Key` header to make retries safe (a replay returns the existing batch).

## Headers

- `Idempotency-Key` string — Client-generated key that identifies this upload attempt.

## Request body

- ReflexAsyncBatchUploadRequest — Rows queued for offline classification at the batch rate.
  - `requests` object[], required — Up to 10,000 rows.
    - `id` string, required — Unique within the batch. Echoed back on each result.
    - `model` string[], required — One or more model names. Always an array on the async endpoint, even for one model.
    - `text` string, required — The text to classify. Up to 350,000 characters.

## Response `200`

Existing batch returned for a replayed `Idempotency-Key`.

- ReflexBatch — Async batch status. `status` moves `queued → in_progress → completed`.
  - `id` string, required — Identifier for the queued batch.
  - `object` string, required — Object type, always `reflex.batch`.
  - `status` 'queued' | 'in_progress' | 'completed', required — Where the batch is in the queue.
  - `request_counts` object, required — Progress counters, advancing as the worker drains the queue.
    - `total` integer, required — Rows accepted into the batch.
    - `completed` integer, required — Rows classified so far.
    - `failed` integer, required — Rows that failed and will not be retried.
  - `created_at` integer, required — Unix timestamp (seconds).

## Other responses

- `201` — Batch queued.
- `400` — Malformed request — missing or invalid fields.
- `401` — Missing or invalid API key.
- `429` — Rate limited — retry after the interval in the Retry-After header.
- `500` — Internal error — safe to retry with backoff.

---

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