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

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

table_id
string<uuid>
required
column_id
string<uuid>
required

Body

application/json

Scope for an on-demand recompute of one formula column.

scope
enum<string>
required

Row scope: all | errored | unfilled | first_n | cell.

Available options:
all,
errored,
unfilled,
first_n,
cell
limit
integer | null

Row count for scope=first_n (default 10).

Required range: 1 <= x <= 10000
offset
integer | null

Starting-row offset in display order for scope=first_n; omit to start at the first row.

Required range: 0 <= x <= 1000000
record_id
string<uuid> | null

The target row for scope=cell; see also record_ids.

record_ids
string<uuid>[] | null

The target rows for scope=cell — a swept selection re-runs in one request rather than one per cell. Wins over record_id when both are sent; scope=cell requires at least one of the two.

Maximum array length: 1000

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