Skip to main content
POST
/
v1
/
tables
/
{table_id}
/
run
Run Table
curl --request POST \
  --url https://api.extruct.ai/v1/tables/{table_id}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "mode": "new"
}'
{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "status": "created",
  "rows": [
    "<string>"
  ],
  "columns": [
    "<string>"
  ],
  "num_requested_cells": 123,
  "mode": "new"
}

​
Overview

This endpoint starts or reruns table execution after rows and columns are ready. It can run the whole table, rerun failures, or scope execution to specific rows or columns.

​
Example request

export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"
export TABLE_ID="YOUR_TABLE_ID"

curl -X POST "https://api.extruct.ai/v1/tables/${TABLE_ID}/run" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -d '{"mode":"new"}'

​
Key parameters

  • table_id (required): target table identifier.
  • mode (optional): run mode. Allowed values: new (default), all, failed.
  • rows (optional): row IDs to scope the run.
  • columns (optional): column IDs to scope the run.
Practical meaning of mode:
  • new: run cells that do not already have values
  • all: rerun every eligible cell in scope
  • failed: rerun only failed cells
Use rows when you want to rerun only a subset of table rows. Use columns when you want to run only specific columns instead of the full schema. When you add new columns to an existing table, the usual pattern is mode: "new" with the new column IDs in columns.

​
Success signal

A successful response returns run metadata (id, status, num_requested_cells). Use GET /v1/tables/{table_id} to track run_status and in-progress counters.

​
Common errors

​
401 Unauthorized

Check that your header is Authorization: Bearer ${EXTRUCT_API_TOKEN}.

​
404 Not Found

The table ID is invalid or unavailable in your workspace.

​
422 Unprocessable Entity

Most often caused by invalid mode, malformed JSON, or invalid row/column IDs.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
table_id
string
required

Body

application/json
​
mode
enum<string>
default:new

Table run execution mode. NEW (default) - run cells without values; ALL - run all cells; FAILED - run failed cells

Available options:
new,
all,
failed
​
rows
string<uuid>[] | null
​
columns
string<uuid>[] | null

Response

Successful Response

​
id
string
required
​
created_at
string<date-time>
required
​
status
enum<string>
required
Available options:
created,
in_progress,
done,
failed
​
rows
string[] | null
required
​
columns
string[] | null
required
​
num_requested_cells
integer
required
​
mode
enum<string>
required
Available options:
new,
all,
failed