Skip to main content
POST
Estimate the credit cost of a row run

Authorizations

X-API-Key
string
header
required

Path Parameters

table_id
string<uuid>
required

Body

application/json

Request body for an on-demand recompute run over rows — two scopes, one body.

Send record_ids to run a checkbox selection. Send all: true to run every row the current listing matches — optionally narrowed by where / row_status, exactly the predicate vocabulary of the rows query, so "run everything matching my filters" and "show me everything matching my filters" can never disagree about what matches. The explicit flag exists so an accidentally empty body runs nothing.

all
boolean
default:false

Run every matching row rather than a named set. Required (and only honoured) when record_ids is absent. At most view_scope_max_rows rows may match; a wider listing is refused with scope_too_large.

record_ids
string<uuid>[] | null

Record IDs of the rows to recompute.

Required array length: 1 - 1000 elements
row_status
enum<string> | null

Narrow an all run to errored or fully computed rows.

Available options:
errored,
fully_computed
where
TableRowsWhereSchema · object | null

Narrow an all run to rows matching this predicate tree.

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.