Scheduled tasks API

Create and manage cron-scheduled tasks that prompt your agents on a schedule

Scheduled tasks API

Schedule recurring prompts for your agents using cron expressions. You can create, update, list, and delete scheduled tasks through these endpoints.

Scheduled tasks are processed by an inline scheduler that runs inside the API process. The scheduler polls for pending tasks every 30 seconds and executes up to 10 tasks per cycle. Each task is dispatched as an HTTP request to the target agent with a 30-second timeout.

Each tick claims due tasks atomically using SELECT ... FOR UPDATE SKIP LOCKED. Tasks are only marked completed when the agent returns a 2xx response. Failed dispatches are re-queued with backoff or marked failed once attempts reaches maxAttempts. See Execution lifecycle below.

All scheduled task endpoints require session authentication. Tasks are scoped to the authenticated user — you can only manage tasks for agents you own.

List scheduled tasks

GET /api/scheduled-tasks

Returns all scheduled tasks for the authenticated user, sorted by creation date (newest first).

Query parameters

Parameter	Type	Required	Description
agentId	string	No	Filter tasks by agent ID

Response

{
  "tasks": [
    {
      "id": "task_abc123",
      "name": "Daily check-in",
      "description": "Morning status update",
      "cronSchedule": "0 9 * * *",
      "prompt": "Give me a morning briefing on today's schedule and priorities.",
      "enabled": true,
      "lastRun": "2026-03-22T09:00:00Z",
      "nextRun": "2026-03-23T09:00:00Z",
      "status": "pending",
      "attempts": 0,
      "maxAttempts": 5,
      "lastError": null,
      "agentId": "agent_456",
      "createdAt": "2026-03-15T12:00:00Z",
      "updatedAt": "2026-03-22T09:00:00Z"
    }
  ],
  "count": 1
}

Task object

Field	Type	Description
id	string	Unique task identifier
name	string	Task name
description	string | null	Optional task description
cronSchedule	string	Cron expression (5 or 6 fields)
prompt	string	The prompt sent to the agent on each run
enabled	boolean	Whether the task is active
lastRun	string | null	ISO 8601 timestamp of the last execution
nextRun	string | null	ISO 8601 timestamp of the next scheduled execution
status	string	Current execution state. One of pending, running, completed, failed. See Execution lifecycle.
attempts	number	Number of dispatch attempts made for the current run. Reset to 0 on the next scheduled trigger.
maxAttempts	number	Maximum dispatch attempts before the task is marked failed. Defaults to 5.
lastError	string | null	Error message from the most recent failed dispatch, or null if the last run succeeded.
agentId	string	ID of the agent this task targets
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last-updated timestamp

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed to list tasks

Create a scheduled task

POST /api/scheduled-tasks

Creates a new scheduled task for one of your agents. The cron schedule is validated to ensure it contains 5 or 6 fields.

Request body

Field	Type	Required	Description
name	string	Yes	Task name
cronSchedule	string	Yes	Cron expression with 5 or 6 fields (for example, "0 9 * * *" for daily at 9 AM)
prompt	string	Yes	The prompt to send to the agent on each run
agentId	string	Yes	ID of the agent to target. Must belong to you.
description	string	No	Optional description
enabled	boolean	No	Whether the task starts active. Defaults to true.

Example request

{
  "name": "Weekly fan report",
  "cronSchedule": "0 10 * * 1",
  "prompt": "Generate a weekly fan engagement report with streaming stats and growth trends.",
  "agentId": "agent_456",
  "description": "Runs every Monday at 10 AM"
}

Response (201 Created)

Returns the created task object.

Errors

Code	Description
400	Missing required fields (name, cronSchedule, prompt, and agentId are required)
400	Invalid cron schedule (expected 5–6 fields)
401	Unauthorized — no valid session
404	Agent not found or does not belong to you
500	Task creation failed

Update a scheduled task

PUT /api/scheduled-tasks

Updates an existing scheduled task. Only the fields you include in the request body are changed.

Request body

Field	Type	Required	Description
taskId	string	Yes	ID of the task to update
name	string	No	Updated task name
description	string	No	Updated description
cronSchedule	string	No	Updated cron expression
prompt	string	No	Updated prompt
enabled	boolean	No	Enable or disable the task

Example request

{
  "taskId": "task_abc123",
  "enabled": false
}

Response

Returns the updated task object.

Errors

Code	Description
400	taskId is required
401	Unauthorized — no valid session
404	Task not found or does not belong to you
500	Task update failed

Delete a scheduled task

DELETE /api/scheduled-tasks

Permanently deletes a scheduled task.

Request body

Field	Type	Required	Description
taskId	string	Yes	ID of the task to delete

Response

{
  "success": true,
  "taskId": "task_abc123"
}

Errors

Code	Description
400	taskId is required
401	Unauthorized — no valid session
404	Task not found or does not belong to you
500	Task deletion failed

Execution lifecycle

Each scheduled task moves through a small state machine driven by the inline scheduler. The status field on the task object reflects the current state.

Status values

Status	Meaning
pending	The task is waiting for its nextRun time. The scheduler will pick it up on the next tick after nextRun <= NOW().
running	The scheduler has claimed this task and is currently dispatching it to the target agent.
completed	The most recent dispatch succeeded — the agent returned a 2xx response. The task will return to pending and nextRun will advance to the next cron tick.
failed	All maxAttempts dispatches failed. The task is no longer retried automatically. Inspect lastError and re-enable manually by issuing a PUT with enabled: true after fixing the underlying issue.

Atomic claim

Each scheduler tick claims due tasks using SELECT ... FOR UPDATE SKIP LOCKED inside a single atomic statement. This guarantees that overlapping ticks, concurrent replicas, or restarted workers can never claim the same task twice. Up to 10 tasks are claimed per tick.

Retry behavior

When a dispatch fails — the agent returns a non-2xx status, the request times out, or the network call raises — the task is settled as follows:

• If attempts < maxAttempts, the task is re-queued. nextRun is set to NOW() + backoff, status is reset to pending, and lastError is updated. The task is picked up again on a future tick.
• If attempts >= maxAttempts, the task is marked failed and stops retrying.

Backoff schedule (linear with a hard cap):

Attempt	Backoff before next retry
1	30 s
2	60 s
3	90 s
4	120 s
5	150 s
6+	300 s (capped)

The backoff is min(30 × attempts, 300) seconds. The default maxAttempts is 5.

Stale-claim recovery

If a worker dies mid-dispatch (process crash, container restart, network partition), the task can be left in running state with no worker driving it forward. On every tick, the scheduler scans for tasks that have been running for more than 10 minutes and returns them to pending with nextRun = NOW(), lastError = "Recovered after stale worker lock". They are then picked up on the next tick.

You should never see a task stuck in running for more than 10 minutes during normal operation.