# Jobs and batches

URL: https://neattrim.com/docs/jobs

The job model, polling and webhooks, batches and idempotency.

A tool call creates a job and returns `202` with the job. A job moves through `queued`, `working` and then one of `completed`, `failed` or `cancelled`.

## Wait for the result

You have two choices.

- **Poll.** `GET /v1/jobs/<id>?wait=<seconds>` holds the request open for up to 45 seconds and answers as soon as the job ends. Poll at most 1 request a second for each job. Status polls do not count against the per-minute limit.
- **Webhook.** Register an endpoint and pass its `webhook_endpoint_id` when you create the job. See [webhooks](https://neattrim.com/docs/webhooks).

Use `GET /v1/jobs/<id>/events` for a stream of progress events. `DELETE /v1/jobs/<id>` cancels a job and releases the time held for it.

## Idempotency

Send an `Idempotency-Key` header on every `POST` that creates something. If your connection drops, send the same request with the same key and you get the original job back. The same key with a different body gets `409 IDEMPOTENCY_MISMATCH`.

## Batches

`POST /v1/batches` runs one tool over many inputs. A batch holds up to 20 files on Free, 100 on Plus and 500 on Pro. `GET /v1/batches/<id>` shows each item and an outputs list. `POST /v1/batches/<id>/cancel` stops the rest. A batch draws from your allowance like the same jobs run one by one.

## Estimate before you run

`POST /v1/estimate` returns how much allowance a call would use and whether it is allowed, without starting a job.
