Skip to main content
POST
Preview a table run

Authorizations

​
X-API-Key
string
header
required

Path Parameters

​
table_id
string<uuid>
required

Body

application/json

What to run: a column, several columns over rows, rows, or every failed cell.

One body for the run and its preview, so the price quoted is the price of the run asked for. kind says which of the fields apply.

​
kind
enum<string>
required

What the run covers. column: one computed column (column_id) over a scope. columns: several columns (column_ids) over chosen rows (record_ids), as one run in dependency order, which is what a swept selection in the grid becomes. rows: chosen rows (record_ids), or every row the view matches (all), across every computed column. failed_cells: only the cells that failed, in every computed column; it takes no other field.

Available options:
column,
columns,
rows,
failed_cells
​
all
boolean
default:false

kind=rows: run every row the view matches (where, row_status) instead of record_ids. At most view_scope_max_rows rows may match; a wider view is refused with scope_too_large.

​
column_id
string<uuid> | null

kind=column: the column to run.

​
column_ids
string<uuid>[] | null

kind=columns: 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.

Required array length: 1 - 100 elements
​
limit
integer | null

kind=column, scope=first_n: how many rows (default 10).

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

kind=column, scope=first_n: the row to start from, in display order; omit to start at the first row.

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

kind=column, scope=cell: the target row; see also record_ids.

​
record_ids
string<uuid>[] | null

The target rows. kind=column with scope=cell (wins over record_id); kind=columns, shared by every column named; kind=rows, the rows to run instead of all. Duplicates are dropped and the order is kept.

Maximum array length: 1000
​
row_status
enum<string> | null

The grid's active smart view (errored or fully computed rows), ANDed with where. kind=column, or kind=rows with all.

Available options:
errored,
fully_computed
​
scope
enum<string>
default:all

kind=column: all | errored | unfilled | first_n | cell. all, errored and first_n share the column's own run: a broader run replaces a narrower one still going, and cells already computed under the same definition are skipped. cell runs are independent of each other.

Available options:
all,
errored,
unfilled,
first_n,
cell
​
sorts
TableRowSortSchema · object[] | null

kind=column: the grid's active sort, so first_n means the first N rows the person can SEE rather than the first N in stored order. Ignored by every other scope.

Maximum array length: 8
​
where
TableRowsWhereSchema · object | null

The grid's active filter, in the rows query's own vocabulary. kind=column: narrows every scope but cell to the matching rows (all runs every matching row, errored / unfilled keep only matching rows, first_n counts within them). kind=rows with all: the rows to run.

Response

Successful Response

What a run would cover and cost, before it is asked for.

Priced by the same plan the run is minted from. Free runs (formula/manual columns) cost nothing and are always sufficient, even at a zero balance. Row counts and cell freshness can still shift between the preview and the run.

​
balance_sufficient
boolean
required

Whether the organization's available credits cover the estimate.

​
cells_total
integer
required

All cells the run would compute over the rows that run, charged or not.

​
estimated_credits
number
required

The most the run can cost, in credits: every row of every paid column charged its full per-row price. What the credit hold and the confirmation gate reason 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).

​
columns
ColumnRunEstimateSchema · object[]

Every enrichment or export column the run would work on, in the order it runs: the column asked for first, then the columns that read it. Each with the most its part can cost and what it usually costs.

​
expected_credits
number
default:0

What a run like this usually costs, in credits: a column charged by use (an AI column) at the share of its per-row maximum the same kind of cell has actually been charged (a typical share while there is no history yet), every other column at its price. Quote both: up to estimated_credits, usually about expected_credits. Equal to estimated_credits for a flat price (no column charged by use, as in a run of enrichments): then quote that one figure, without up to.

​
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. The run skips them and charges nothing for them, so they are already subtracted from rows_in_scope and from the price.

​
rows_in_scope
integer
default:0

Rows the run would compute. 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.