Skip to main content
POST
Estimate the credit cost of a multi-column run

Authorizations

X-API-Key
string
header
required

Path Parameters

table_id
string<uuid>
required

Body

application/json

Cell-scoped run over several columns at once, as ONE dependency-ordered plan.

column_ids
string<uuid>[]
required

The computed columns to run, in any order. A column another one here feeds is planned once, AFTER its input, so no column reads a value a sibling is still computing. Sending one request per column instead is what makes them race.

Required array length: 1 - 100 elements
record_ids
string<uuid>[]
required

The target rows, shared by every column named — a swept selection is a rectangle. Duplicates are dropped and the order is kept.

Required array length: 1 - 1000 elements

Response

Successful Response

Estimated credit cost of an on-demand column run, before running it.

Free runs (formula/manual columns) estimate to zero and are always sufficient, even at a zero balance. The figure is an estimate: row counts and cell freshness can shift between estimating and running.

balance_sufficient
boolean
required

Whether the organization's available credits cover the estimate.

cells_total
integer
required

All cells the run would compute, charged or not.

estimated_credits
number
required

Worst-case credit cost of the run (every waterfall rung runs) — the number the confirmation gate reasons about.

is_estimate
boolean
required

Always true: freshness and row counts can shift by run time.

unit_price
number
required

Blended credits per charged cell (total estimate / units); 0 for free runs.

units
integer
required

Cells that would incur a charge (0 for free runs).

expected_credits
number
default:0

Expected credit cost under the waterfall resolution curve (80% of rows answer on the first rung, 95% by the second). Equal to estimated_credits when the run has no waterfall columns. Quote THIS to the user; charging is exact per row.

export_writes
ExportWriteEstimateSchema · object[]

Export columns this run would fire. Present so the confirmation can name the destination, the object and the action instead of only a row count. Empty for a run that writes nothing outside this table.

requires_confirmation
boolean
default:false

True when the estimate crosses the confirmation threshold — ask before spending instead of running on first click.

rows_held_back
integer
default:0

Rows in scope the column's run condition would hold back. Already subtracted from rows_in_scope.

rows_in_scope
integer
default:0

Rows the run would cover. This is what a scope choice is about, and what the credit estimate is derived from; cells_total also counts the dependent columns the run would recompute.

scope_too_large
boolean
default:false

True when the filtered view names more rows than a run may be scoped to (view_scope_max_rows). rows_in_scope still carries the matching count; the run itself would be refused with scope_too_large. Narrow the filter, or run the whole table.