Skip to main content
POST
Set a table's refresh cadence

Authorizations

X-API-Key
string
header
required

Path Parameters

table_id
string<uuid>
required

Body

application/json

Set up a table's refresh cadence.

frequency
enum<string>
required

A preset, or 'custom' for an interval.

Available options:
hourly,
daily,
weekly,
monthly,
quarterly,
custom
delete_missing_rows
boolean
default:false

Delete rows whose records have gone from the source. Forces every scheduled run to re-list everything, and is capped per run so a provider outage cannot empty the table.

hour
integer
default:9

Local hour to run at.

Required range: 0 <= x <= 23
interval_unit
enum<string> | null

Required for a custom cadence.

Available options:
hours,
days,
weeks,
months
interval_value
integer | null

Required for a custom cadence.

Required range: 0 < x <= 365
minute
integer
default:0

Local minute to run at.

Required range: 0 <= x <= 59
time_zone
string | null

IANA zone the time is in; defaults to UTC. An unknown zone falls back to UTC.

Maximum string length: 64

Response

Successful Response

A table's refresh cadence.

created_at
string<date-time>
required
delete_missing_rows
boolean
required

Whether a scheduled run deletes rows whose records are gone from the source. Forces every scheduled run to re-list everything, since a changes-only fetch cannot tell a deleted record from an unchanged one.

frequency
enum<string>
required

How often a table re-imports, in the vocabulary the settings panel offers.

The presets are stored as cron because "the 8th of every month at 09:00" is a calendar statement that an interval cannot make: an interval of 30 days drifts off the date within a year. CUSTOM is the escape hatch for "every N days/weeks/months", which is an interval and drifts on purpose, anchored to when the user set it up.

HOURLY is cron too, and it is the one preset that ignores the hour the user picked: "every hour at 09:00" is not a thing anyone means. The minute is kept, so an hourly refresh set at 09:20 runs at twenty past every hour, and a source that rate-limits is not hit by every table on the hour.

Available options:
hourly,
daily,
weekly,
monthly,
quarterly,
custom
hour
integer
required

Local hour the cadence runs at.

id
string<uuid>
required
interval_unit
enum<string> | null
required

The unit a CUSTOM cadence counts in.

HOURS is the only one with no time of day to honour: "every 6 hours at 09:00" is two statements that cannot both be true. It anchors to the next occurrence of the chosen MINUTE instead, the same way the HOURLY preset keeps the minute and drops the hour.

Available options:
hours,
days,
weeks,
months
interval_value
integer | null
required

How many units apart, for a custom cadence.

last_skip_reason
enum<string> | null
required

Why the last firing skipped, alongside last_skipped_at.

Available options:
source_detached,
run_in_progress
last_skipped_at
string<date-time> | null
required

When a firing last skipped without starting a run; null if it never has.

minute
integer
required

Local minute the cadence runs at.

next_run_at
string<date-time>
required
next_runs
string<date-time>[]
required

The next few fire times, so a cadence can be checked before it is trusted.

paused
boolean
required
table_id
string<uuid>
required
time_zone
string
required

IANA zone the run time is expressed in.

updated_at
string<date-time>
required