Scheduling

Uranus provides flexible scheduling capabilities for automated task execution.

Schedule Types

One-Time (once)

Execute a task at a specific time:

{
  "type": "once",
  "name": "Send Report",
  "next_run": "2024-12-15T09:00:00Z",
  "callback_type": "workflow",
  "callback_id": "report-workflow"
}

Delayed (delayed)

Execute after a delay in seconds:

{
  "type": "delayed",
  "name": "Follow-up Email",
  "delay_seconds": 3600,
  "callback_type": "workflow",
  "callback_id": "followup-workflow"
}

Cron (cron)

Recurring execution with cron expressions:

{
  "type": "cron",
  "name": "Daily Sync",
  "cron_expression": "0 9 * * *",
  "callback_type": "workflow",
  "callback_id": "sync-workflow"
}

Cron Expressions

Format

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

Common Patterns

Expression	Description
* * * * *	Every minute
0 * * * *	Every hour
0 9 * * *	Daily at 9:00 AM
0 9 * * 1	Every Monday at 9:00 AM
0 9 1 * *	First of every month at 9:00 AM
0 */2 * * *	Every 2 hours
0 9-17 * * 1-5	Hourly 9-5 on weekdays
0 0 1 1 *	Yearly on January 1st

Special Characters

Character	Meaning
*	Any value
,	Value list (1,3,5)
-	Range (1-5)
/	Step values (*/5)

Creating Schedules

Via Dashboard

1. Navigate to Schedules
2. Click New Schedule
3. Select schedule type
4. Configure timing
5. Select callback (workflow or function)
6. Save

Via API

curl -X POST https://your-domain.com/api/agents/{id}/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cron",
    "name": "Hourly Check",
    "cron_expression": "0 * * * *",
    "callback_type": "workflow",
    "callback_id": "check-workflow",
    "status": "active"
  }'

Schedule Status

Status	Description
active	Schedule is running
paused	Temporarily disabled
completed	One-time schedule finished
failed	Execution failed

Callback Types

Workflow

Trigger a workflow:

{
  "callback_type": "workflow",
  "callback_id": "my-workflow-id"
}

Function

Call a specific function:

{
  "callback_type": "function",
  "callback_id": "processData"
}

Execution Mechanism

Schedules are executed via Durable Object alarms:

┌─────────────────────────────────────┐
│         Durable Object               │
│                                      │
│  ┌─────────────────────────────┐    │
│  │    Alarm Triggered          │    │
│  └──────────────┬──────────────┘    │
│                 │                    │
│                 ▼                    │
│  ┌─────────────────────────────┐    │
│  │  Query Pending Schedules    │    │
│  │  WHERE next_run <= NOW()    │    │
│  └──────────────┬──────────────┘    │
│                 │                    │
│                 ▼                    │
│  ┌─────────────────────────────┐    │
│  │   Execute Callback          │    │
│  │   (workflow or function)    │    │
│  └──────────────┬──────────────┘    │
│                 │                    │
│                 ▼                    │
│  ┌─────────────────────────────┐    │
│  │  Calculate Next Run         │    │
│  │  (for cron schedules)       │    │
│  └──────────────┬──────────────┘    │
│                 │                    │
│                 ▼                    │
│  ┌─────────────────────────────┐    │
│  │  Set Next Alarm             │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

Cron Builder

The dashboard includes a visual cron builder:

• Select frequency (minute, hour, day, week, month)
• Pick specific times
• Preview next execution times
• Generate cron expression

Managing Schedules

Pause a Schedule

curl -X PUT https://your-domain.com/api/agents/{id}/schedules/{scheduleId} \
  -d '{"status": "paused"}'

Resume a Schedule

curl -X PUT https://your-domain.com/api/agents/{id}/schedules/{scheduleId} \
  -d '{"status": "active"}'

Delete a Schedule

curl -X DELETE https://your-domain.com/api/agents/{id}/schedules/{scheduleId}

Calendar Integration

Schedules can be visualized on the calendar:

1. Go to Calendar in the sidebar
2. View scheduled tasks by day/week/month
3. Click events to see details
4. Drag to reschedule

Calendar Tasks

Calendar tasks are schedule-like entries with additional metadata:

{
  "title": "Team Standup",
  "start_time": "2024-12-15T09:00:00Z",
  "end_time": "2024-12-15T09:30:00Z",
  "recurrence": "weekly",
  "recurrence_days": [1, 2, 3, 4, 5],
  "workflow_id": "standup-workflow"
}

Best Practices

1. Use Descriptive Names

{
  "name": "Daily Customer Report - 9AM EST"
}

2. Set Appropriate Intervals

Avoid over-scheduling:

• Consider rate limits
• Account for execution time
• Leave buffer between runs

3. Handle Failures

Configure retry logic:

{
  "workflow_retry_attempts": 3,
  "workflow_retry_delay": 60
}

4. Monitor Execution

Check schedule history:

• View last run status
• Check execution logs
• Set up alerting

5. Use Timezones

Always specify timezone for clarity:

{
  "calendar_timezone": "America/New_York"
}

Timezone Handling

Schedules respect the agent's configured timezone:

{
  "calendar_timezone": "America/New_York",
  "calendar_working_hours_start": "09:00",
  "calendar_working_hours_end": "17:00"
}

Cron expressions are evaluated in the agent's timezone.

API Reference

See Schedules API for complete endpoint documentation.