Schedules

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

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
• description: Schedule description

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
• description: Schedule description

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
}

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: Either "agent" or "action-chain"
• instructions: Instructions for the handler
• agentId: Required if handlerType is "agent"
• actionChainId: Required if handlerType is "action-chain"

Optional Fields:

• inputMapping: Key-value mapping for action chain inputs (Handlebars syntax)

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",
    "timestamp": "{{currentTime}}",
    "environment": "production"
  }
}

Response: Returns created ScheduleHandler object

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 or actionChainId) even if not changing them.

Response: Returns updated ScheduleHandler 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:

Use Handlebars syntax to provide dynamic values:

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

Available Variables:

• {{currentTime}} - Current timestamp
• {{currentDate}} - Current date
• {{triggerId}} - Schedule trigger ID
• {{organizationId}} - Organization ID

Use Cases:

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

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

• Minimum Interval: 1 minute (cannot schedule more frequently)
• Timezone: All schedules run in UTC
• No Manual Trigger: Cannot manually trigger a schedule (create a handler execution instead)
• Handler Limit: Maximum 100 handlers per schedule
• Execution History: Not tracked (use conversation/chain logs instead)

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