Skip to main content
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 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

Bulk Calculate · Get Bulk Calculate Batch

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.
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.

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).
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.

2. Poll until the batch finishes

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.

Reading the counts

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} 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:
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. 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.
  • 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.