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:
- Submit the batch and receive a
batchId. - Poll until
stateiscompletedorfailed. - Read every item’s results from the final poll.
Endpoints
1. Submit the batch
Each item is what a single calculate takes (atemplateCode 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 is422, 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 returns409 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
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
Oncestate 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:
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
summaryCheckStatusispass:summaryCheckistrueor a number from 0 to 1. failmeans the check evaluated and failed.summaryCheckFailReasonsis present only then.errormeans the check could not be evaluated, and there is nosummaryCheck. Treat it as not passing. The item still readsstatus: "solved"and is counted insummary.checkErrored.not_evaluatedmeans the calculator defines no governing check. Such an item reportssummaryCheck: true, so read the status, notsummaryCheck.
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 onerror.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;reflets 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
batchIdfrom the409or check the project’s sheets first.