prompt, works in the workspace, and reuses its tables. Each execution spends the organization’s credits. Scheduled runs belong to the organization of the user who created the key.
Create and start
A new scheduled run is adraft. It does not run until you activate it.
prompt that is complete on its own, and name the table to extend if there is one.
cadence takes one of these forms. time is HH:mm in timezone, an IANA time zone.
Status
POST /v1/scheduled-runs/{id}/runstarts one execution now, also on adraftorpausedscheduled run. Each call starts another billed execution.PATCHkeeps the status. On anactivescheduled run,next_run_atis computed again. A scheduled run that belongs to a play cannot be changed here:PATCHanswers409 scheduled_run_belongs_to_play. Change it on the play, in the app.DELETEis final and cancels an execution already queued. The workspace and its tables stay.- A scheduled run that belongs to a play moves with its play when you activate or pause it. Activating it also restarts the sequences of the play, which can refuse with one of the sender or sequence codes below. It cannot be deleted through this API: delete the play in the app.
Know when an execution ends
There is no webhook. PollGET /v1/scheduled-runs/{id}/runs, or read latest_run on GET /v1/scheduled-runs/{id}. All /v1 rate limits apply, so poll once every minute or more.
An attempt that fails is retried, so an execution can stay
running for a while before it gets its final status.
trigger is schedule or manual. error is null unless the execution failed or was cancelled. It is then a stable code: for example scheduled_run_paused, scheduled_run_archived, scheduled_run_max_attempts_exceeded, or the general scheduled_run_failed.
What a scheduled run delivers
GET /v1/scheduled-runs and GET /v1/scheduled-runs/{id} return results: one entry per table the scheduled run delivers. During an execution, the agent declares which tables these are, for example a table of companies and a table of people. A scheduled run of a play delivers the play’s table. Until an execution declares a table, results is empty: no table is counted.
Each table is counted on its own. Do not add up two tables: they hold different things.
Report
qualified when has_criteria is true, otherwise rows.
What each execution added
GET /v1/scheduled-runs/{id}/runs gives each execution results: for each delivered table, the rows created between the start and the end of the execution (until now while it runs). results is null until the execution starts.
new_qualified is null when the table has no criteria: then report new_rows. The counts read the tables delivered today, so a table declared later is counted for earlier executions too. A row someone adds in the app during an execution is counted with it.
Read the new rows
An execution adds its rows to the tables of the workspace. Rows have no creation date orsince filter. To process only the new rows of the delivered tables:
- Wait until the execution is over.
- Take the tables from
results. Every table of the workspace is listed bylinks.tables, which isGET /v1/workspaces/{id}/tables. - Read every page of each table with
GET /v1/tables/{id}/rows. See pagination. - Keep the
idof each row you have processed. A row whoseidyou have not seen is new.
succeeded execution, the sourced_by_run value of a row shows the date of the execution that brought it, in the time zone of the scheduled run. Older rows show Setup. This value is written after the execution ends, and only if that step succeeds. Use it to display the origin of a row, and use row ids to decide what is new.