Skip to main content
A scheduled run repeats one mission on a cadence, in one workspace. Each execution is a list-building agent run that gets the saved 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 a draft. It does not run until you activate it.
Nobody answers the agent during an execution. Write a 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}/run starts one execution now, also on a draft or paused scheduled run. Each call starts another billed execution.
  • PATCH keeps the status. On an active scheduled run, next_run_at is computed again. A scheduled run that belongs to a play cannot be changed here: PATCH answers 409 scheduled_run_belongs_to_play. Change it on the play, in the app.
  • DELETE is 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. Poll GET /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 or since filter. To process only the new rows of the delivered tables:
  1. Wait until the execution is over.
  2. Take the tables from results. Every table of the workspace is listed by links.tables, which is GET /v1/workspaces/{id}/tables.
  3. Read every page of each table with GET /v1/tables/{id}/rows. See pagination.
  4. Keep the id of each row you have processed. A row whose id you have not seen is new.
After a 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.

Errors