Scheduled Tasks API

Overview

Scheduled tasks let you run automated actions on a recurring schedule using cron expressions. Each task can trigger an agent chat, execute a workflow, or call a webhook at the specified interval.

Action Types

---

Endpoints

List Scheduled Tasks

GET /api/v1/scheduled-tasks

Query Parameters:

Response:

jsonCopy
{
  "data": [
    {
      "id": "st_abc123",
      "name": "Daily Sales Report",
      "cron": "0 9 * * 1-5",
      "action_type": "workflow_execution",
      "action_config": {
        "workflow_id": "wf_abc123",
        "input": { "report_type": "daily" }
      },
      "enabled": true,
      "last_run_at": "2026-01-15T09:00:00Z",
      "next_run_at": "2026-01-16T09:00:00Z",
      "created_at": "2026-01-01T10:00:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}

Create Scheduled Task

POST /api/v1/scheduled-tasks

Request Body:

Action Config: agent_chat

Action Config: workflow_execution

Action Config: webhook_call

Example -- Daily workflow at 9 AM on weekdays:

bashCopy
curl -X POST /api/v1/scheduled-tasks \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Sales Report",
    "cron": "0 9 * * 1-5",
    "timezone": "America/New_York",
    "action_type": "workflow_execution",
    "action_config": {
      "workflow_id": "wf_abc123",
      "input": { "report_type": "daily" }
    },
    "enabled": true
  }'

Example -- Hourly agent check-in:

bashCopy
curl -X POST /api/v1/scheduled-tasks \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly System Check",
    "cron": "0 * * * *",
    "action_type": "agent_chat",
    "action_config": {
      "agent_id": "agent_abc123",
      "message": "Run a system health check and report any issues.",
      "store_response": true
    }
  }'

Example -- Weekly webhook ping:

bashCopy
curl -X POST /api/v1/scheduled-tasks \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Analytics Export",
    "cron": "0 2 * * 0",
    "action_type": "webhook_call",
    "action_config": {
      "url": "https://analytics.yourcompany.com/export",
      "method": "POST",
      "headers": { "X-API-Key": "your_analytics_key" },
      "body": { "period": "weekly" }
    }
  }'

Get Scheduled Task

GET /api/v1/scheduled-tasks/:id

Update Scheduled Task

PUT /api/v1/scheduled-tasks/:id

Accepts the same fields as creation. Only provided fields are updated.

Delete Scheduled Task

DELETE /api/v1/scheduled-tasks/:id

Toggle Task (Enable/Disable)

POST /api/v1/scheduled-tasks/:id/toggle

Toggles the enabled state of the task.

Response:

jsonCopy
{
  "id": "st_abc123",
  "enabled": false,
  "next_run_at": null
}

Execution History

GET /api/v1/scheduled-tasks/:id/executions

Query Parameters:

Response:

jsonCopy
{
  "data": [
    {
      "id": "ste_abc123",
      "task_id": "st_abc123",
      "status": "success",
      "started_at": "2026-01-15T09:00:00Z",
      "completed_at": "2026-01-15T09:00:12Z",
      "duration_ms": 12000,
      "result": {
        "workflow_execution_id": "exec_xyz789",
        "output": { "report_url": "https://..." }
      }
    },
    {
      "id": "ste_def456",
      "task_id": "st_abc123",
      "status": "failed",
      "started_at": "2026-01-14T09:00:00Z",
      "completed_at": "2026-01-14T09:00:05Z",
      "duration_ms": 5000,
      "error": "Workflow wf_abc123 not found"
    }
  ],
  "total": 30,
  "page": 1,
  "per_page": 20
}

Preview Next Run Times

Preview when a cron expression will fire next without creating a task.

POST /api/v1/scheduled-tasks/preview

Request Body:

bashCopy
curl -X POST /api/v1/scheduled-tasks/preview \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 9 * * 1-5",
    "timezone": "America/New_York",
    "count": 5
  }'

Response:

jsonCopy
{
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "next_runs": [
    "2026-01-16T09:00:00-05:00",
    "2026-01-19T09:00:00-05:00",
    "2026-01-20T09:00:00-05:00",
    "2026-01-21T09:00:00-05:00",
    "2026-01-22T09:00:00-05:00"
  ],
  "description": "At 09:00 AM, Monday through Friday"
}

---

Cron Expression Reference

Cron expressions use the standard 5-field format:

┌───────── minute (0-59)
│ ┌───────── hour (0-23)
│ │ ┌───────── day of month (1-31)
│ │ │ ┌───────── month (1-12)
│ │ │ │ ┌───────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Common Examples

---

Error Codes