---
title: "Several calculator runs in one request, each answered or refused on its own"
method: POST
path: "/calculate-batch"
tags: ["Agent tools"]
---

# Several calculator runs in one request, each answered or refused on its own

`POST /calculate-batch`

## Request

- Base URL: `https://api.craftquantities.com/v1`
- URL: `https://api.craftquantities.com/v1/calculate-batch`
- Auth: none declared

## Query parameters

- `detail` 'full' | 'summary': full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read.
- `format` 'json' | 'md'

## Request body

- object
  - `items` object[], required: The runs, 1 to 25, each one calculator and its inputs; answered in the same order.
    - `slug` string, required: The calculator's slug or permanent id, such as concrete-calculator or cq-c0201.
    - `inputs` object: The calculator's input values, by input id (an unknown id is refused with the accepted ids). A length, area, volume or other measured input takes "12 ft", "3.5 m", "8' 3 1/2\"" or {"value": 12, "unit": "ft"}; a count or percentage takes a number; a select takes one of its option values. Inputs left out take the value the calculator's page opens on.
    - `system` 'metric' | 'imperial': The unit system inputs left out open in, and the one the page link opens in. The answer comes in both.
    - `market` 'US' | 'CA' | 'UK' | 'AU' | 'INTL': Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures.
    - `inputUnits` 'base': Send "base" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit.
    - `ref` string: The caller's own label for this run, returned with its result.
  - `system` 'metric' | 'imperial': The unit system for every run that does not name its own.
  - `market` 'US' | 'CA' | 'UK' | 'AU' | 'INTL': The market for every run that does not name its own.
  - `inputUnits` 'base': Send "base" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit.

## Response `200`

One entry per run, in order: the calculator's answer or that run's refusal.

- union
  - object
    - `engine` object, required
    - `counts` object, required
      - `asked` integer, required
      - `answered` integer, required
      - `refused` integer, required
    - `results` union[], required: One entry per run, in the order asked: the calculator's full answer, or why that run was refused. One refusal leaves the others answered.
      - union
        - object
          - `index` integer, required
          - `ref` string
          - `ok` unknown, required
          - `result` object, required
            - `engine` object, required
              - …
            - `calculator` object, required
              - …
            - `system` 'metric' | 'imperial', required
            - `market` string, nullable
            - `inputs` object[], required: Every input the calculation ran on, and where each came from.
              - …
            - `result` object, required
              - …
            - `sources` object[], required
              - …
            - `citation` object, required
              - …
            - `links` object, required
              - …
            - `licence` object, required
              - …
            - `notice` string, required
            - `explain` object: Only when explain is true. Each figure is the calculator's own; no step is a formula written for the engine.
              - …
        - object
          - `index` integer, required
          - `ref` string
          - `ok` unknown, required
          - `error` object, required
            - `type` string
            - `title` string, required
            - `status` integer, required
            - `problems` object[], required
              - …
            - `didYouMean` string[]
    - `licence` object, required
      - `name` string, required
      - `url` string, required
      - `attribution` string, required
    - `notice` string, required
  - object
    - `detail` 'summary', required
    - `tool` string, required
    - `title` string, required
    - `lines` object[], required: The result lines, as the report's table gives them.
    - `notes` string[], required: What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary.
    - `citation` string, required: The one citation line, built from the answer's own data.
    - `url` string, nullable, required
    - `open` string, nullable, required
    - `more` string, nullable, required

## Other responses

- `400`: The request was refused; every problem is listed.
- `413`: The request was refused; every problem is listed.

---

[API](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api.md) · [All operations](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api/llms.txt) · [OpenAPI document](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api/revisions/a69883abc23b?raw)