> ## Documentation Index
> Fetch the complete documentation index at: https://connectionshub.atlastube.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk calculate

> Run up to 100 connection calculations in one call, then poll once for every result.

Run up to **100 calculators** in one project with a single request, then poll for every item's results. Each item is saved as a sheet in the project, exactly as a single [`calculate`](https://connectionshub.atlastube.com/docs/api/reference/templates/run-a-calculation-using-a-template) saves one. Use it for a set of connections designed together, such as every beam-to-column connection on a floor.

This is an **asynchronous** flow:

1. Submit the batch and receive a `batchId`.
2. Poll until `state` is `completed` or `failed`.
3. Read every item's results from the final poll.

## Endpoints

```
POST /v1/sheets/bulk-calculate                    → submit a batch, returns batchId
GET  /v1/projects/{projectId}/batches/{batchId}   → poll; items appear when terminal
```

[Bulk Calculate](https://connectionshub.atlastube.com/docs/api/reference/templates/bulk-calculate.md) · [Get Bulk Calculate Batch](https://connectionshub.atlastube.com/docs/api/reference/templates/get-bulk-calculate-batch.md)

## 1. Submit the batch

Each item is what a single calculate takes (a `templateCode` and `attributes`), plus an optional `ref` of your own that is echoed back on that item's result. Items can use different templates.

```bash theme={null}
curl -X POST "https://api.calcs.com/v1/sheets/bulk-calculate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "56b9335c-6859-4978-a6ec-33d780599c23",
    "items": [
      { "ref": "B1", "templateCode": "steelConnectionHssBeamToHssMomentAISC360-22", "preset": "Fin Plate",
        "attributes": { "design_method": "LRFD", "member_beam": "HSS8X4X.375", "member_column": "HSS10X10X.500" } },
      { "ref": "B2", "templateCode": "steelConnectionHssBeamToHssMomentAISC360-22", "preset": "Fin Plate",
        "attributes": { "design_method": "LRFD", "member_beam": "HSS10X4X.375", "member_column": "HSS10X10X.500" } },
      { "ref": "BP1", "templateCode": "steelConnectionHssBasePlateAISC360-22",
        "attributes": { "sectionSize": "HSS10X10X.500", "f_c": "4000 psi", "F1554_Grade": "Grade 55" } }
    ]
  }'
```

| Field | Required | Description |
| - | - | - |
| `projectId` | yes | Project the sheets are created in |
| `items[]` | yes | 1 to 100 items, reported back in this order |
| `items[].templateCode` | yes | Template to create the sheet from |
| `items[].attributes` | yes | Input values keyed by widget reference ID, as for a single calculate. An item without one is refused |
| `items[].ref` | no | Your identifier for the item, up to 64 characters, unique within the batch |
| `items[].name` | no | Sheet name. Defaults to the template name plus the item's `ref` or position |
| `items[].preset` | no | A preset code to apply before `attributes` |

A **`201 Created`** means the batch was accepted. The body is the batch status with `items: null`. The `Location` header is the path to poll (relative to the API base) and `Retry-After` says how many seconds to wait.

```json theme={null}
{
  "batchId": "5ab97d3e-0030-4eaa-8c40-99057f2051f6",
  "type": "bulk-calculate",
  "state": "processing",
  "progressPercent": 0,
  "projectId": "56b9335c-6859-4978-a6ec-33d780599c23",
  "itemCount": 3,
  "summary": { "total": 3, "solved": 0, "errored": 0, "stale": 0, "checkErrored": 0, "pending": 3 },
  "createdAt": "2026-09-21T05:57:50.080Z",
  "completedAt": null,
  "durationSeconds": null,
  "error": null,
  "items": null
}
```

### Accepted whole or rejected whole

If **any** item is invalid, the response is **`422`**, nothing is created, and `details` lists every problem across every item, each prefixed with its item (for example `items[2].templateCode`).

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid bulk calculate request.",
    "details": [
      { "field": "items[1].templateCode", "message": "No template found with that code." },
      { "field": "items[2].attributes", "message": "attributes must be a JSON object." }
    ]
  }
}
```

`code` is `TOO_MANY_ITEMS` when the batch exceeds 100 items, and `VALIDATION_ERROR` otherwise.

### One batch per project at a time

While a batch is running for a project, another submission for that project returns **`409`** with `code: "BATCH_IN_PROGRESS"`. The running batch's ID is in `details` under `field: "batchId"`. Poll it, and resubmit once it finishes.

```json theme={null}
{
  "error": {
    "code": "BATCH_IN_PROGRESS",
    "message": "This project already has a bulk calculation in progress.",
    "details": [
      { "field": "batchId", "message": "5ab97d3e-0030-4eaa-8c40-99057f2051f6" }
    ]
  }
}
```

## 2. Poll until the batch finishes

```bash theme={null}
curl "https://api.calcs.com/v1/projects/{projectId}/batches/{batchId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

While the batch runs, `state` is `processing`, `progressPercent` and `summary.solved` advance, and `items` is `null`. `Location` and `Retry-After` are on every response until the batch finishes, then absent.

| Field | Description |
| - | - |
| `batchId` | The batch's identifier, the one you poll |
| `type` | Always `bulk-calculate` |
| `projectId` | Project the batch's sheets were created in |
| `itemCount` | Number of items the batch was submitted with |
| `state` | `processing`, `completed`, or `failed`. Treat an unrecognised value as still in progress |
| `progressPercent` | Share of the batch's sheets solved so far, 0 to 100. It can trail `summary.solved` by a poll and reads 100 once `completed`. Read `summary` for the outcome, not this |
| `summary` | `total`, `solved`, `errored`, `stale`, `checkErrored`, `pending`. While `processing`, `pending` can briefly read `0` before `state` changes, so poll on `state`, never on `pending` |
| `error` | Why the batch itself failed |
| `items` | `null` until the batch finishes, then one entry per item in request order |
| `createdAt` | When the batch was accepted |
| `completedAt` | When the batch finished. `null` until then |
| `durationSeconds` | How long the batch took, set once it finishes. It can stay `null` on a `failed` batch that stopped without recording one |

### Reading the counts

| Counter | Means | What to do |
| - | - | - |
| `solved` | Results were computed from the inputs the sheet holds now | Read them |
| `errored` | The batch could not produce results for the item | Retry |
| `stale` | The batch solved the sheet, and its inputs changed afterwards (usually you edited it) | Re-solve that sheet, or resubmit the item |
| `checkErrored` | The sheet solved, but its governing check produced no verdict. Also counted in `solved` | The results are current; there is no pass/fail to read |

`pending` is `total - solved - errored - stale`. To confirm every item is usable, check that `errored`, `stale` and `checkErrored` are **all** `0`.

**Counts on a finished batch are not frozen.** They are recomputed from the sheets' current state on every poll. A batch that read `solved: 3` can later read `solved: 2, stale: 1` after someone edits one of its sheets, still `completed` and with no error. Record the outcome when you first read the finished batch if you need it as it stood.

### How long to poll

`Retry-After` is **2 seconds**. Read it from the header rather than hard-coding it. Duration depends on the number of items and the templates used.

A batch that stops reporting progress is declared abandoned after **10 minutes** without progress while `processing`, or **1 hour** while still queued. It then polls as `failed` with `BATCH_ABANDONED`, and you can resubmit its items. You don't need your own timeout for the batch to end; add one only if you want to give up sooner.

## 3. Read the results

Once `state` is `completed` or `failed`, `items` holds one entry per item, in request order. Each solved item is **exactly what [`GET /v1/sheets/{sheetId}`](https://connectionshub.atlastube.com/docs/api/reference/sheets/get-sheet) returns for that sheet**, plus your `ref`, so one parser handles both. A failed batch lists every item too: the ones it solved before failing carry results, the rest carry the batch's error.

Abbreviated, with illustrative values:

```json theme={null}
{
  "batchId": "5ab97d3e-0030-4eaa-8c40-99057f2051f6",
  "state": "completed",
  "summary": { "total": 3, "solved": 3, "errored": 0, "stale": 0, "checkErrored": 0, "pending": 0 },
  "items": [
    {
      "ref": "B1",
      "sheetId": "84cb248b-a36f-41a9-9639-575bc597341e",
      "templateCode": "steelConnectionHssBeamToHssMomentAISC360-22",
      "status": "solved",
      "inputs": { "member_beam": "HSS8X4X.375", "…": "more" },
      "results": { "…": "template outputs" },
      "summaryCheck": 0.71,
      "summaryCheckStatus": "pass",
      "sheetUrl": "https://app.calcs.com/project/56b9335c-6859-4978-a6ec-33d780599c23/sheet/84cb248b-a36f-41a9-9639-575bc597341e"
    }
  ]
}
```

An item may also carry `warnings`, the same non-fatal findings a single calculate returns: an attribute the template does not define (`unknown_field`) or a `null` value. The item still solved; the named field was not applied. An item with no results carries `status: "unsolved"` and an `error` explaining why.

A `completed` batch can have `summary.solved` of `0`: every item ran, and none could be solved. `state` is `failed` only when the batch itself could not run, or stopped reporting progress (`BATCH_ABANDONED`); `error` says which. Either way, `summary.pending` is `0` once the batch finishes.

## Reading the verdict

* **An item passes** when `summaryCheckStatus` is `pass`: `summaryCheck` is `true` or a number from 0 to 1.
* `fail` means the check evaluated and failed. `summaryCheckFailReasons` is present only then.
* `error` means the check could not be evaluated, and there is **no** `summaryCheck`. Treat it as not passing. The item still reads `status: "solved"` and is counted in `summary.checkErrored`.
* `not_evaluated` means the calculator defines no governing check. Such an item reports `summaryCheck: true`, so read the status, not `summaryCheck`.

To know every item is usable, check that `summary.errored` and `summary.checkErrored` are both `0`, not `errored` alone.

**Never read `passed` as the verdict.** It is deprecated, and a failing calculation can report `true`, even on its first solve.

## Errors

Errors arrive at three levels. Branch on `error.code`, not the message.

| `error.code` | Level | Status | Means |
| - | - | - | - |
| `VALIDATION_ERROR` | Request | `400` / `422` | Malformed JSON, or an item or field failed. Nothing was created |
| `TOO_MANY_ITEMS` | Request | `422` | More than 100 items. Nothing was created |
| `BATCH_IN_PROGRESS` | Request | `409` | A batch is already running for this project |
| `NOT_FOUND` | Request | `404` | The project or batch does not exist or is not accessible with this key |
| `BATCH_FAILED` | Batch | `200` | The batch could not be run |
| `VALIDATION_CHANGED` | Batch | `200` | A template became unavailable between acceptance and processing |
| `BATCH_ABANDONED` | Batch | `200` | The batch stopped reporting progress and will not resume. Resubmit its items |
| `SOLVE_FAILED` | Item | `200` | The solver could not answer this sheet. Retry the batch. If every item reports this, the cause is usually not your inputs, so retry before changing them |
| `RESULTS_STALE` | Item | `200` | The sheet's inputs changed after the batch solved it: edited in the app, patched through the API, the project's defaults changed, or the sheet was upgraded. Counted in `stale`, not `errored`. Solve the sheet again, or resubmit the item |
| `SHEET_UNAVAILABLE` | Item | `200` | The sheet was deleted after the batch ran, or the batch stopped before creating it. Resubmit the item |
| `TEMPLATE_NOT_FOUND` | Item | `200` | The template is no longer accessible with this key |

Batch- and item-level errors arrive inside a successful poll: a failed batch is still a `200` on `GET`, with `state: "failed"` and an `error`. Only request-level errors use a 4xx status. A batch-level code also appears on each unfinished item, so an item carrying `BATCH_FAILED`, `VALIDATION_CHANGED` or `BATCH_ABANDONED` means the batch stopped, not that the item was at fault. Treat an unrecognised code at any level as a failure to retry.

## Notes

* **Order and `ref`.** Items come back in request order; `ref` lets you match results without relying on position.
* **Sheets persist.** They are ordinary sheets in the project. Open them via `sheetUrl`, or delete them with [bulk delete](https://connectionshub.atlastube.com/docs/api/guides/deleting.md).
* **Retries.** Resubmitting an identical batch after the first completed creates a second set of sheets. If you are unsure whether a submission went through, poll the `batchId` from the `409` or check the project's sheets first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.