---
title: "Batch — run up to 20 calc sub-requests in one call"
method: POST
path: "/v1/batch"
tags: ["Platform"]
---

# Batch — run up to 20 calc sub-requests in one call

`POST /v1/batch`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/batch`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Runs up to 20 calculation sub-requests in a single call, in order, returning one result per sub-request. Each sub-request is dispatched through the same authenticated, metered handler as a direct REST call (so it records one usage event and is validated identically), and a sub-failure (bad path, bad body) is isolated — it does not fail the batch, which always returns 200. Sub-request paths must be calc routes (no /v1/batch nesting, no /v1/usage or /v1/signup). Rate limiting is all-or-nothing: the batch reserves one token per sub-request up front and is rejected whole with 429 if the budget can't cover them. The whole batch shares one calc deadline budget. Deterministic — identical batches produce an identical result_id.

## Request body

- BatchRequest
  - `requests` object[], required: The sub-requests to run, in order.
    - `path` string, required: A calc route path, e.g. /v1/tvm (no /v1/batch nesting).
    - `body` object, required: The sub-request body, exactly as the endpoint expects.

## Response `200`

One result per sub-request, in order (sub-failures are isolated, not fatal)

- BatchResponse
  - `result_id` string
  - `engine_version` string
  - `result` object
    - `results` object[]: One entry per sub-request, order preserved.
      - `status` integer: The sub-request's HTTP status (200, 400, 503, …).
      - `body` object: The sub-request's response body (a result envelope, or an error).
  - `disclaimer` string

## Other responses

- `400`: Invalid request (malformed JSON, or not 1–20 sub-requests)
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)