> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retriever.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled runs

> Repeat a list-building mission on a cadence: create, change, pause, start, delete, and read what each execution brought.

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.

| Endpoint | Body | Response |
| - | - | - |
| `POST /v1/scheduled-runs` | `workspace_id`, `title`, `prompt`, `cadence`, `timezone` | `201`, the scheduled run as a draft |
| `GET /v1/scheduled-runs` | Query: optional `workspace_id` | `items`, each with `latest_run` |
| `GET /v1/scheduled-runs/{id}` | | The scheduled run with `latest_run` |
| `PATCH /v1/scheduled-runs/{id}` | At least one of `title`, `prompt`, `cadence`, `timezone` | The scheduled run |
| `POST /v1/scheduled-runs/{id}/activate` | None | The scheduled run, `active` |
| `POST /v1/scheduled-runs/{id}/pause` | None | The scheduled run, `paused` |
| `POST /v1/scheduled-runs/{id}/run` | None | `202`, the new execution |
| `GET /v1/scheduled-runs/{id}/runs` | | `items`: the 50 most recent executions, newest first |
| `DELETE /v1/scheduled-runs/{id}` | None | The scheduled run, `archived` |

## Create and start

A new scheduled run is a `draft`. It does not run until you activate it.

```bash theme={null}
curl -X POST https://api.retriever.run/v1/scheduled-runs \
  -H "Authorization: Bearer $RETRIEVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_123",
    "title": "New funded fintechs",
    "prompt": "Find French fintechs funded in the last 30 days and add them to the Accounts table.",
    "cadence": { "frequency": "weekly", "weekday": 1, "time": "09:00" },
    "timezone": "Europe/Paris"
  }'

curl -X POST https://api.retriever.run/v1/scheduled-runs/$SCHEDULE_ID/activate \
  -H "Authorization: Bearer $RETRIEVER_API_KEY"
```

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.

| `frequency` | Other fields | Runs |
| - | - | - |
| `daily` | `time` | Every day |
| `weekly` | `weekday` (1 is Monday, 7 is Sunday), `time` | Once a week |
| `interval` | `every_days` (1 to 30), `time` | Every N days |

## Status

| `status` | Meaning | `next_run_at` |
| - | - | - |
| `draft` | Created, never activated | `null` |
| `active` | Runs on its cadence | The next slot |
| `paused` | The cadence is stopped. An execution the cadence already queued is cancelled | `null` |
| `archived` | Deleted. `GET /v1/scheduled-runs` leaves it out; `GET /v1/scheduled-runs/{id}` still returns it | `null` |

* `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](https://docs.retriever.run/concepts/rate-limits.md) apply, so poll once every minute or more.

| `status` of an execution | Over? |
| - | - |
| `queued`, `running` | No |
| `succeeded`, `failed`, `cancelled` | Yes |

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.

| Field | Meaning |
| - | - |
| `table_id`, `table_name`, `row_entity_type` | The table, and what one row is (`person`, `company`, `post`…) |
| `has_criteria` | `true` when the table has qualification criteria |
| `rows` | All rows of the table |
| `qualified` | Rows that meet the criteria. `null` when the table has no criteria |
| `links.rows` | `GET /v1/tables/{id}/rows` |

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.

```json theme={null}
{ "table_id": "tbl_people", "new_rows": 42, "new_qualified": 12 }
```

`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](https://docs.retriever.run/concepts/pagination.md).
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

| Status | Code | When |
| - | - | - |
| `400` | `invalid_request` | Invalid body or query, or an unknown field |
| `400` | `scheduled_run_timezone_invalid` | `timezone` is not an IANA time zone |
| `400` | `no_sender_available`, `sender_pool_required`, `sender_pool_invalid`, `sender_not_visible`, `sender_not_active`, `sender_pool_missing_channel`, `sequence_has_no_actionable_step` | `activate` on a scheduled run of a play whose sequence cannot start. `message` says what to fix |
| `404` | `scheduled_run_not_found` | Unknown id, or another organization's scheduled run |
| `404` | `workspace_not_found` | Unknown `workspace_id` on create |
| `409` | `scheduled_run_archived` | The scheduled run was deleted |
| `409` | `scheduled_run_belongs_to_play` | `PATCH` or `DELETE` on the scheduled run of a play |
| `415` | `invalid_request` | `POST` create or `PATCH` without `Content-Type: application/json` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.