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

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

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

Check the run times:

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"}'

{"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"}

Create the task:

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.

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, or with a key that has the lab scope through Lab.

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}.

Schedule an agent

Endpoints

Fields

Create a weekly task

Run status

On this page