# Batching

> Send lists to the Curriculo API: per-endpoint ceilings, single-item aliases, order guarantees, per-item errors, billing, and scoring a backlog against one job.

**Source:** /docs/batching/ (Curriculo Docs)  
**Updated:** 12 October 2026  
**Contact:** hello@curriculo.me

There is no separate batch endpoint. **The list is the batch,** and one request returns every result. Send one item and you get the answer directly; send several and results come back in the order you sent them, one per item.

A list is billed as one request: ten CVs in one `/parse/` call cost $0.01. See [Pricing and billing](/docs/pricing/).

## Ceilings per operation

| Operation | List field | Ceiling | Single-item alias |
|---|---|---|---|
| `/parse/` | `files` | 10 documents | `file` |
| `/evaluate/` | `resume_pdfs`, against one job | 10 documents | `resume_pdf` |
| `/translate/` | `texts`, or `files` | 200 strings and 50,000 characters, or 10 documents | `text` |
| `/detect-language/` | `texts` | 200 texts | `text` |
| `/summary/` | JSON array of interviews, or repeated `media` | 10 interviews or files | a single object |
| `/prompt/` | none | one instruction per call (stateful) | none |
| `/parse/async`, `/evaluate/async` | `file_urls`, `resume_urls` | 25 links | none |

## Three properties to design around

1. **Order is preserved.** `results[i]` always belongs to input `i`.
2. **Failures are per item.** A bad document returns an error entry beside the successful ones, and the HTTP status stays `200`.
3. **The batch answers inside the request budget.** Items that never started before the 300-second budget ran out return a `504` entry rather than sinking the whole request. Resubmit just those.

Re-sending a failed item is always safe. It cannot create duplicates or half-finished records.

## Backlogs larger than one request

For a backlog, prefer the [async lane](/docs/background-processing/): `POST /parse/async` or `POST /evaluate/async` takes up to 25 links per task, answers at once, and delivers the result by callback or polling.

Heavy work runs three operations at a time on capacity shared across the service; beyond that, requests queue rather than fail. Sustained throughput is roughly 2 to 4 CVs per minute and varies with load. If you need materially more, tell us the volume. See [Rate limits](/docs/rate-limits/).

> [!TIP]
> CV parsing takes 40 to 90 seconds per document. Treat CV processing as a background job, not a page load, and keep your client timeout above five minutes.

## Evaluating a backlog against one job

Register the description once (free), then send lists of CVs against the `job_id` it returns. Inline `job_details` does the same job, but registering keeps a long backlog from re-sending the same paragraph with every request.

```bash
# 1. Register the job. Returns a job_id.
curl -X POST https://api.curriculo.me/public/jobs/ \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{"job_details": "Senior backend engineer, Python and FastAPI, Seoul", "label": "BE-Seoul"}'
# -> {"job_id": "job_abc123", "label": "BE-Seoul"}

# 2. Evaluate a list of CVs against it.
curl -X POST https://api.curriculo.me/public/evaluate/ \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -F 'resume_pdfs=@candidate_a.pdf' \
  -F 'resume_pdfs=@candidate_b.docx' \
  -F 'job_id=job_abc123'
```

See [Register a job](/docs/api/jobs/) and [Evaluate a candidate](/docs/api/evaluate/).