# Run one tool over many inputs (every account, within its allowance)

URL: https://neattrim.com/docs/api/create-batch

POST /v1/batches: Run one tool over many inputs (every account, within its allowance).

Endpoint: `POST /v1/batches`

Who can call it: An API key, or an OAuth token for an app.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Required on POSTs that create a job, upload, checkout, plan change or top-up; stored 24 h per ledger subject; same key with a different body returns 409 IDEMPOTENCY_MISMATCH |
| `Neattrim-Simulate` | header | string | no | Test keys only (km_test_). Forces a deterministic outcome such as completed, failed or LIMIT for sandbox tests; ignored with live keys |

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | any | yes |  |
| `settings` | object | no |  |
| `inputs` | array of object | yes |  |
| `webhook_endpoint_id` | string | no |  |

## Examples

Set NEATTRIM_API_KEY to your key, then copy an example. A tool that draws from your allowance reads an uploaded file: upload a sample file as in the quickstart and set VIDEO_FILE_ID (or AUDIO_FILE_ID, IMAGE_FILE_ID, SUBTITLES_FILE_ID) to its file_id. Any other id in an example, such as JOB_ID, is read from a variable of the same name.

### curl

```bash
curl -X POST "https://api.neattrim.com/v1/batches" \
  -H "Authorization: Bearer $NEATTRIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"tool\":\"probe_media\",\"inputs\":[{\"source\":\"$VIDEO_FILE_ID\"},{\"source\":\"$AUDIO_FILE_ID\"}]}"
```

### TypeScript

```ts
// @neattrim/sdk is not on npm yet: it arrives with the first client release. Use the curl example today.
import { api, Neattrim, unwrap } from "@neattrim/sdk";

const client = new Neattrim({ apiKey: process.env.NEATTRIM_API_KEY });
const result = unwrap(
  await api.createBatch({
    client: client.client,
    body: {
      "tool": "probe_media",
      "inputs": [
        {
          "source": process.env.VIDEO_FILE_ID
        },
        {
          "source": process.env.AUDIO_FILE_ID
        }
      ]
    },
  }),
);
console.log(result);
```

### Python

```python
# neattrim is not on PyPI yet: it arrives with the first client release. Use the curl example today.
import os

from neattrim import Neattrim
from neattrim_generated.api.batches import create_batch
from neattrim_generated.models import BatchCreate

with Neattrim(api_key=os.environ["NEATTRIM_API_KEY"], base_url="https://api.neattrim.com") as client:
    result = create_batch.sync(client=client.client, body=BatchCreate.from_dict({"tool": "probe_media", "inputs": [{"source": os.environ["VIDEO_FILE_ID"]}, {"source": os.environ["AUDIO_FILE_ID"]}]}))
    print(result)
```

## Response 202

Batch

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `batch_id` | string | yes |  |
| `tool` | string | no |  |
| `status` | any | yes |  (one of "queued", "working", "completed", "cancelled") |
| `items` | array of object | yes |  |
| `usage` | any | no |  |
| `zip_url` | string or null | no |  |

## Errors

- `400`: BAD_REQUEST
- `401`: UNAUTHENTICATED or INACTIVE
- `402`: LIMIT (allowance used), NEEDS_PLAN (paid feature) or DECLINED
- `413`: TOO_BIG or TOO_LONG for the caller's plan
- `422`: SOURCE_REFUSED, PART_CORRUPT, CONTENT_REFUSED, NOT_HEARD, TOO_SHORT or CHECKOUT_UNAVAILABLE
- `429`: RATE_LIMITED
