Skip to main content
POST
Refresh a table from its source now

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

Body

application/json

What kind of refresh to run.

Two independent asks, not one dial. Re-fetching every record is safe and routine; deleting local rows whose records are gone is destructive and deliberate. Both default to off, so a plain refresh stays the cheap incremental one.

delete_missing_rows
boolean
default:false

Delete imported rows whose records the source no longer returns. Implies a full re-list, and is refused while the source has a row limit — a capped import cannot tell a deleted record from one it never fetched.

full_relist
boolean
default:false

Re-fetch every record instead of only those changed since the last run. Updates rows; never deletes any.

Response

Successful Response

One import run's progress and outcome.

error
string | null
required
finished_at
string<date-time> | null
required
id
string<uuid>
required
is_full_relist
boolean
required

Whether this run asked the provider for everything.

rows_created
integer
required
rows_deleted
integer
required
rows_skipped
integer
required

Records returned without the source's identity field, and so dropped.

rows_updated
integer
required
source_id
string<uuid>
required
started_at
string<date-time>
required
status
enum<string>
required

Where one import run has got to.

The terminal states are absorbing: a run never leaves them. There is no PENDING here — unlike a CSV upload, which sits parsed and uncommitted until the user says go, a source run is only ever created at the moment something decides to run it.

CANCELLING is a request, not an outcome. Stopping an import is a database status flip the workflow observes between pages, never a Temporal terminate: a terminate could land mid-page and leave rows half-written with nothing to settle the run, which is exactly the stuck state that blocks every future refresh of the table.

Available options:
running,
cancelling,
cancelled,
succeeded,
failed
sweep_deletions
boolean
required
table_id
string<uuid>
required
trigger
enum<string>
required

What asked for a run.

Available options:
initial,
manual,
scheduled
error_code
string | null

Classified cause of the failure: unauthorized, rate_limited, server_unavailable, network_error, not_found, pagination_error, bad_request. NULL when the run did not fail.

needs_reconnect
boolean
default:false

Whether fixing this means reconnecting the integration. Only true for a credentials failure, so the prompt keeps its meaning.