> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Schedule an agent

Schedule an agent [#schedule-an-agent]

A scheduled task runs one agent with one prompt on a schedule. Each run is saved as a chat of the task's owner, the key owner with a workspace key.

Endpoints [#endpoints]

Every route needs `X-Space-Slug`. On a deployment without scheduling every route returns `404`.

| Method   | URL                                                         | Does                                                                                       | Auth          |
| -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------- |
| `POST`   | `/api/v1/scheduled-tasks/preview/`                          | The next run times for a schedule: `{next_runs, expires_at}`, in UTC                       | Key or bearer |
| `POST`   | `/api/v1/scheduled-tasks/`                                  | Create; `201` with `id`, `next_run_at`, `expires_at`, `enabled`                            | Key or bearer |
| `GET`    | `/api/v1/scheduled-tasks/`                                  | The caller's tasks in the workspace, each with `last_run`                                  | Key or bearer |
| `PATCH`  | `/api/v1/scheduled-tasks/{task_id}/`                        | Change any create field, or `{"enabled": false}` to pause and `true` to resume             | Key or bearer |
| `GET`    | `/api/v1/scheduled-tasks/{task_id}/runs/?limit=50&offset=0` | Runs, newest first: `scheduled_for`, `status`, `thread_id`, `error`, `skipped_connections` | Key or bearer |
| `DELETE` | `/api/v1/scheduled-tasks/{task_id}/`                        | Delete; `204`                                                                              | Key or bearer |
| `POST`   | `/api/v1/scheduled-tasks/{task_id}/run-now/`                | Run once now                                                                               | Bearer only   |

Tasks are private to their owner: another member's `GET /api/v1/scheduled-tasks/` does not list them.

Fields [#fields]

| Field             | Rule                                                                                                      |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| `name`            | Required, 1–50 characters                                                                                 |
| `prompt`          | Required; the user message each run sends                                                                 |
| `agent_id`        | Required; an `id` from `GET /api/v1/agents-v2/agents/`                                                    |
| `model_config_id` | Optional; omitted, the agent's model                                                                      |
| `schedule`        | Required; below                                                                                           |
| `timezone`        | Required; an IANA name such as `Europe/Rome`. `WAT` and other abbreviations return `422`                  |
| `expires_at`      | Optional. Omitted: 7 days for `daily`, 1 month for `weekly`, 3 months for `monthly`; `null` never expires |

| `schedule.frequency` | Needs                                                  | `time`                                     |
| -------------------- | ------------------------------------------------------ | ------------------------------------------ |
| `daily`              | —                                                      | `HH:MM`, on a 5-minute step, in `timezone` |
| `weekly`             | `weekdays`: `MO` `TU` `WE` `TH` `FR` `SA` `SU`         | same                                       |
| `monthly`            | `month_day`: 1–31; a month without that day is skipped | same                                       |
| `once`               | `date`: `YYYY-MM-DD`                                   | same                                       |

A field that the frequency does not use returns `422`, such as `weekly schedules take no month_day`.

Create a weekly task [#create-a-weekly-task]

1. Check the run times:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/scheduled-tasks/preview/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"schedule": {"frequency": "weekly", "time": "09:00", "weekdays": ["MO", "TH"]}, "timezone": "Europe/Rome"}'
   ```

   ```json
   {"next_runs": ["2026-10-22T07:00:00Z", "2026-10-26T08:00:00Z", "2026-10-29T08:00:00Z"], "expires_at": "2026-11-20T14:08:19.816892Z"}
   ```

2. Create the task:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/scheduled-tasks/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Weekly contract digest",
       "prompt": "Summarize contracts that expire in the next 30 days.",
       "agent_id": 36,
       "schedule": {"frequency": "weekly", "time": "09:00", "weekdays": ["MO"]},
       "timezone": "Europe/Rome"
     }'
   ```

   The response is `201` with `"next_run_at": "2026-10-26T08:00:00Z"` and `"enabled": true`.

3. Follow the runs with `GET /api/v1/scheduled-tasks/{task_id}/runs/`. Each run's `thread_id` is the chat it wrote; read it signed in, as in [Read and share chats](chats), or with a key that has the `lab` scope through [Lab](../lab/overview).

Run status [#run-status]

| `status`               | Meaning                                                      |
| ---------------------- | ------------------------------------------------------------ |
| `queued`, `running`    | Waiting · in progress                                        |
| `done`                 | Finished                                                     |
| `failed`               | Could not start or ended with an error; see `error`          |
| `ended_without_result` | Interrupted                                                  |
| `cancelled`            | Stopped by the owner                                         |
| `quota`                | The owner's credits ran out                                  |
| `missed`               | Started too late and skipped; missed runs are never replayed |

After several failed runs in a row the task pauses itself: `enabled` becomes `false` and `paused_reason` `failures`. Resume with `{"enabled": true}`.