Schedules

Schedule recurring tasks to run at specified times using cron expressions. Schedules can trigger agents or action chains automatically.

Overview

Schedules consist of:

1. Trigger - Defines when to execute (cron expression)
2. Handlers - Define what to execute (agent or action chain)

A single schedule can have multiple handlers that all execute when the trigger fires.

Schedule Management

List Schedules

GET /orgs/{organizationId}/schedules

Required Role: Admin or Owner

Query Parameters:

• limit (optional): Number of results (default: 20)
• cursor (optional): Pagination offset
• actionChainId (optional): Filter by action chain
• agentId (optional): Filter by agent
• workflowId (optional): Filter by workflow

Response:

{
  "items": [
    {
      "triggerId": "trigger-123",
      "organizationId": "org-456",
      "name": "Daily Report",
      "description": "Generate daily sales report",
      "cronExpression": "0 9 * * *",
      "creatorUserId": "user-789",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalRows": 1,
  "offset": 0
}

Create Schedule

POST /orgs/{organizationId}/schedules

Required Role: Admin or Owner

Required Fields:

• name: Schedule name
• cronExpression: Cron expression defining when to run

Optional Fields:

• description: Schedule description
• confirmHighFrequency: Set true to allow a cron that fires more often than every 15 minutes (see Limitations)

Request Body:

{
  "name": "Daily Report",
  "description": "Generate daily sales report at 9 AM",
  "cronExpression": "0 9 * * *"
}

Cron Expression Format:

minute hour day-of-month month day-of-week

Examples:

• 0 9 * * * - Every day at 9:00 AM
• */15 * * * * - Every 15 minutes
• 0 */4 * * * - Every 4 hours
• 0 9 * * 1 - Every Monday at 9:00 AM
• 0 0 1 * * - First day of every month at midnight
• 30 14 * * 5 - Every Friday at 2:30 PM

Response: Returns created ScheduleTrigger object

Get Schedule

GET /orgs/{organizationId}/schedules/{triggerId}

Required Role: Admin or Owner

Response: Returns ScheduleTrigger object

Update Schedule

PUT /orgs/{organizationId}/schedules/{triggerId}

Required Role: Admin or Owner

Required Fields:

• name: Schedule name
• cronExpression: Cron expression

Optional Fields:

• description: Schedule description
• confirmHighFrequency: Set true to allow tightening to a cadence more frequent than every 15 minutes

Request Body:

{
  "name": "Updated Daily Report",
  "description": "Generate daily sales report at 10 AM instead",
  "cronExpression": "0 10 * * *"
}

Response: Returns updated ScheduleTrigger object

Delete Schedule

DELETE /orgs/{organizationId}/schedules/{triggerId}

Required Role: Admin or Owner

Permanently deletes the schedule trigger and all its handlers.

Response:

{
  "success": true
}

Get Schedule Runs

GET /orgs/{organizationId}/schedules/{triggerId}/runs

Required Role: Admin or Owner

Returns the next scheduled firing and the most recent run across all handlers attached to the trigger.

Response:

{
  "nextRun": "2024-01-02T09:00:00Z",
  "lastRun": {
    "handlerId": "handler-123",
    "handlerType": "agent",
    "runId": "run-456",
    "status": "success",
    "startedAt": "2024-01-01T09:00:00Z",
    "endedAt": "2024-01-01T09:00:12Z"
  },
  "hasUntrackedWorkflowRuns": false
}

nextRun is null if the cron expression fails to parse; lastRun is null when nothing has run yet. hasUntrackedWorkflowRuns is true when a workflow handler has runs that could not be surfaced (e.g. aged out of Step Functions retention).

Schedule Handlers

Handlers define what actions to execute when a schedule triggers.

List Handlers

GET /orgs/{organizationId}/schedules/{triggerId}/handlers

Required Role: Admin or Owner

Query Parameters:

• limit (optional): Number of results (default: 20)
• cursor (optional): Pagination offset

Response:

{
  "items": [
    {
      "handlerId": "handler-123",
      "triggerId": "trigger-456",
      "organizationId": "org-789",
      "handlerType": "agent",
      "agentId": "agent-101",
      "agentName": "Report Generator",
      "instructions": "Generate and send the daily sales report",
      "inputMapping": null,
      "creatorUserId": "user-202",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalRows": 1,
  "offset": 0
}

Create Handler

POST /orgs/{organizationId}/schedules/{triggerId}/handlers

Required Role: Admin or Owner

Required Fields:

• handlerType: One of "agent", "action-chain", or "workflow"
• instructions: Instructions for the handler
• agentId: Required if handlerType is "agent"
• actionChainId: Required if handlerType is "action-chain"
• workflowId: Required if handlerType is "workflow"

Optional Fields:

• inputMapping: Flat string-to-string map passed to the action chain / workflow at execution time

Agent Handler Example:

{
  "handlerType": "agent",
  "agentId": "agent-123",
  "instructions": "Generate a daily sales report including total revenue, top products, and new customers. Email the report to the sales team."
}

Action Chain Handler Example:

{
  "handlerType": "action-chain",
  "actionChainId": "chain-456",
  "instructions": "Run the data backup workflow",
  "inputMapping": {
    "backupType": "daily",
    "environment": "production"
  }
}

Response: Returns created ScheduleHandlerView object (includes populated agentName / actionChainName / workflowName)

Get Handler

GET /orgs/{organizationId}/schedules/{triggerId}/handlers/{handlerId}

Required Role: Admin or Owner

Response: Returns ScheduleHandlerView object with agent/chain name populated

Update Handler

PUT /orgs/{organizationId}/schedules/{triggerId}/handlers/{handlerId}

Required Role: Admin or Owner

Request Body:

{
  "handlerType": "agent",
  "agentId": "agent-123",
  "instructions": "Updated instructions for the handler",
  "inputMapping": {
    "key": "value"
  }
}

Note: You must provide handlerType, instructions, and the appropriate ID (agentId, actionChainId, or workflowId) even if not changing them. Note that only instructions and inputMapping are persisted — the handler type and target ID cannot be changed on an existing handler.

Response: Returns updated ScheduleHandlerView object

Delete Handler

DELETE /orgs/{organizationId}/schedules/{triggerId}/handlers/{handlerId}

Required Role: Admin or Owner

Removes the handler from the schedule.

Response:

{
  "success": true
}

Handler Types

Agent Handler

Executes an agent with the provided instructions when the schedule triggers.

Behavior:

• Creates a new conversation for each execution
• Agent runs autonomously with the given instructions
• Can use all tools attached to the agent
• No user interaction during execution

Use Cases:

• Generate periodic reports
• Monitor systems and alert on issues
• Perform regular data analysis
• Send scheduled notifications

Action Chain Handler

Executes an action chain workflow when the schedule triggers.

Input Mapping:

inputMapping is a flat map of string keys to string values, passed through to the action chain / workflow when the schedule fires:

{
  "inputMapping": {
    "reportType": "daily",
    "recipients": "sales@company.com"
  }
}

At execution time a currentTimestamp key (current ISO-8601 time) is added automatically if you don’t supply one.

Use Cases:

• Multi-step workflows
• Data processing pipelines
• Automated testing
• System maintenance tasks

Workflow Handler

Executes a workflow (handlerType: "workflow" with a workflowId) when the schedule triggers. Like action-chain handlers, workflow handlers accept an inputMapping.

Example Use Cases

Daily Sales Report

Schedule:

{
  "name": "Daily Sales Report",
  "description": "Generate and email sales report every morning",
  "cronExpression": "0 9 * * *"
}

Handler:

{
  "handlerType": "agent",
  "agentId": "sales-report-agent",
  "instructions": "Generate a comprehensive sales report for yesterday including: total revenue, number of orders, top 10 products, and new customer count. Email the report to sales@company.com with charts and insights."
}

Weekly Data Backup

Schedule:

{
  "name": "Weekly Backup",
  "description": "Run weekly data backup every Sunday at 2 AM",
  "cronExpression": "0 2 * * 0"
}

Handler:

{
  "handlerType": "action-chain",
  "actionChainId": "backup-workflow",
  "instructions": "Execute weekly backup workflow",
  "inputMapping": {
    "backupType": "weekly",
    "retention": "30",
    "notify": "devops@company.com"
  }
}

Hourly System Check

Schedule:

{
  "name": "Hourly Health Check",
  "description": "Check system health every hour",
  "cronExpression": "0 * * * *"
}

Handler:

{
  "handlerType": "agent",
  "agentId": "monitoring-agent",
  "instructions": "Check all critical systems: API response times, database connections, queue depths, and error rates. Alert via Slack if any metrics are outside normal ranges."
}

Monthly Report

Schedule:

{
  "name": "Monthly Business Review",
  "description": "Generate monthly business report on the 1st of each month",
  "cronExpression": "0 9 1 * *"
}

Handler:

{
  "handlerType": "agent",
  "agentId": "analytics-agent",
  "instructions": "Generate monthly business review including: revenue trends, customer growth, product performance, and key metrics comparison vs last month. Create a presentation-ready report and email to executives@company.com."
}

Cron Expression Reference

Basic Patterns

Field Values

Special Characters

• * - Any value
• , - Value list separator (e.g., 1,15 = 1st and 15th)
• - - Range (e.g., 1-5 = Monday through Friday)
• / - Step values (e.g., */10 = every 10 units)

Best Practices

1. Clear Naming - Use descriptive names that explain what and when
2. Timezone Awareness - All times are in UTC; adjust accordingly
3. Test First - Test handlers manually before scheduling
4. Monitor Executions - Review logs to ensure schedules run successfully
5. Avoid Overlap - Don’t schedule long-running tasks too frequently
6. Error Handling - Build error handling into agent instructions
7. Notification - Have agents send notifications on completion/failure
8. Documentation - Document what each schedule does in the description

Limitations

• High-Frequency Guard: Crons firing more often than every 15 minutes are rejected unless you pass confirmHighFrequency: true
• Timezone: All schedules run in UTC
• No Manual Trigger: Cannot manually trigger a schedule (create a handler execution instead)
• Execution History: Use GET /schedules/{triggerId}/runs for the latest run and next firing; full history lives in the conversation / chain / workflow logs

Troubleshooting

Monitoring Schedule Executions

Agent Handlers

Agent handlers create conversations that can be viewed in the conversations list. Filter by agent ID to see scheduled executions.

Action Chain Handlers

Action chain executions can be monitored through the action chains execution logs.

Best Practice

Include notification steps in your handlers to get alerts when schedules run:

{
  "instructions": "Generate the report, then send a Slack message to #reports channel confirming completion with a summary."
}