# Start a bulk run (POST /v1/bulk/runs)

> POST /v1/bulk/runs: Start a bulk run. border.bot API reference (Bulk).

Source: https://border.bot/docs/api/start-bulk-run

> Documentation index: https://border.bot/llms.txt. Every page is Markdown at its URL + `.md`.

`POST https://api.border.bot/v1/bulk/runs`

Requires an API key (`Authorization: Bearer bb_live_…`).

Classify, calculate, find agency product codes or find and check countries of origin for up to 10,000 items in the background. Each item is charged when it runs (as its single request would be) and refunded if it fails; a run stops when your credits run out. Follow it with `GET /bulk/status`, read its answers with `GET /bulk/results`.

API key scope: `bulk`.

## Request body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |

## Responses

- `200`: The run, queued. (`BulkRunResponse`)
- `400`: Invalid input (`invalid_input`). (`Error`)
- `401`: Missing, invalid, revoked or expired API key (`unauthorized`). (`Error`)
- `403`: The API key doesn’t have the `bulk` scope (`forbidden`, `details.reason: "missing_scope"`). (`Error`)
- `429`: Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota. (`Error`)
- `500`: Unexpected error (`internal`). (`Error`)

## Example

```bash
curl -X POST 'https://api.border.bot/v1/bulk/runs' \
  -H 'Authorization: Bearer bb_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"classify","reference":"catalogue-2026-10","items":[{"description":"Men'\''s cotton t-shirt","destinationCountry":"US"},{"description":"Stainless steel water bottle, 750 ml","destinationCountry":"GB"}]}'
```