Uranus

Appearance

Scheduling ​

Uranus provides flexible scheduling capabilities for automated task execution.

Schedule Types ​

One-Time (once) ​

Execute a task at a specific time:

json
{
  "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:

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

Cron (cron) ​

Recurring execution with cron expressions:

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

Cron Expressions ​

Expressions are evaluated in the agent's calendar timezone (settings.calendar.timezone; UTC when unset) — the Worker itself runs in UTC. Supported: *, numbers, lists, ranges, steps on any of those (*/15, 1-5/2), month and weekday names (jan…dec, sun…sat) and 7 for Sunday. When both day-of-month and day-of-week are restricted the job runs when either matches (standard cron), so 0 9 1 * mon fires on the 1st and on Mondays. Expressions that can never match (0 0 31 2 *) fall back to one hour ahead with a warning.

Format ​

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

Common Patterns ​

ExpressionDescription
* * * * *Every minute
0 * * * *Every hour
0 9 * * *Daily at 9:00 AM
0 9 * * 1Every 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-5Hourly 9-5 on weekdays
0 0 1 1 *Yearly on January 1st

Special Characters ​

CharacterMeaning
*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 ​

bash
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 ​

StatusDescription
activeSchedule is running
pausedTemporarily disabled
completedOne-time schedule finished
failedExecution failed

Callback Types ​

Workflow ​

Trigger a workflow:

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

Function ​

Call a specific function:

json
{
  "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 ​

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

Resume a Schedule ​

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

Delete a Schedule ​

bash
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:

json
{
  "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 ​

json
{
  "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:

json
{
  "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:

json
{
  "calendar_timezone": "America/New_York"
}

Timezone Handling ​

Schedules respect the agent's configured timezone:

json
{
  "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.

Copyright © 2026 Uranus