Calculations List Calculations
calculations_list_calculationsRead-onlyIdempotent
List calculations for the tenant.
Paged newest-first by default with a slim projection — no analytics
blob, to keep the list response cheap. Walk the whole collection by
following next_cursor (or the Link header) until has_more is
false; count is this page's size, never the total.
To reconcile a bulk run against your own records, page with
order=asc and a created_after bound: rows come oldest-first, so
calculations submitted while you are still walking land after your
position instead of shifting rows under it.
Optional part_id narrows the result to a single part. Optional
ids turns this into the bulk polling surface: poll one request per
sweep, not one per calculation.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Comma-separated calculation IDs (max 500). THE polling surface for bulk clients: one weight-1 sweep returns the status of every listed calculation, instead of N weight-1 detail requests that exhaust the per-org rate budget (self-DoS). When set, `limit` and ordering are ignored and every matching row is returned. | |
| sort | No | Ordering key. Rows with no value yet (an in-flight run has no unit cost) sort last in both directions. Ignored when `ids` is set. `offer_price` orders on the price each calculation headlines and the comparison ranks on (the item's `offer_price`; an assembly priced only in part states none and sorts last); `unit_cost` on the cost before the cost-sheet surcharges. `created_at`, `lot_size` and `annual_volume` support `cursor`; `unit_cost`, `offer_price` and `finished_at` are null until a run settles, so a cursor over them cannot reach every row and is rejected — those three return the first page only. | created_at |
| limit | No | Maximum rows to return in one page. | |
| order | No | Sort direction over the collection's ordering key. Use `asc` to reconcile a batch: rows come oldest-first, so work created while you page lands after your position instead of shifting rows under it. | desc |
| cursor | No | Opaque position token from the previous page's `next_cursor` (or the `Link` / `X-Next-Cursor` response header). Omit it for the first page. Keep every other query parameter identical for the whole walk — a cursor replayed against different filters is rejected. | |
| part_id | No | ||
| batch_id | No | Narrow to one batch's calculations — e.g. every cell of a multi-environment comparison grid. Pair with the batch comparison endpoint, which returns the pivoted matrix. | |
| created_after | No | Only rows created at or after this instant (RFC 3339, e.g. `2026-07-20T09:00:00Z`). Inclusive. | |
| include_total | No | Also return the total number of rows matching the query, across all pages. Off by default because it costs an extra scan; `has_more` is the cheap way to know whether to keep paging. | |
| status_filter | No | Filter by lifecycle status (e.g. queued, running, succeeded, failed, cancelled). Repeatable; several values are OR-ed. | |
| created_before | No | Only rows created strictly before this instant (RFC 3339). Exclusive, so an `after`/`before` pair tiles a range without overlap. | |
| include_facets | No | Also return `facets`: status and material values with counts, each computed over everything the OTHER active filters allow. | |
| material_grade_id | No | Only runs priced against one of these material grades. Repeatable; several values are OR-ed, so passing every value is the same as passing none. | |
| include_components | No | With `part_id`: also list the calculations this part received as a component of an assembly (each at the lot the assembly implied). Ignored without `part_id`. | |
| parent_calculation_id | No | Only the component calculations of this assembly. By default the list contains top-level calculations only — assembly components are reachable through their parent. |