Scheduled Execution

Run workflows automatically on a schedule using cron expressions.

Scheduled execution requires Cloud features to be enabled.

Overview

Schedule workflows to run automatically at specific times or intervals. Perfect for daily reports, weekly summaries, hourly data syncs, or any recurring automation.

Basic Usage

Add a schedule to your workflow using the .schedule() method:

1import { relay } from "@relayplane/sdk";
2
3const workflow = relay
4  .workflow("daily-summary")
5  .schedule("0 9 * * *")  // Every day at 9 AM
6  .step("gather")
7  .with("openai:gpt-4o")
8  .prompt("Gather yesterday's data")
9  .step("summarize")
10  .with("anthropic:claude-sonnet-4-20250514")
11  .depends("gather")
12  .prompt("Generate summary report");
13
14// Deploy the scheduled workflow
15await workflow.deploy();

Cron Syntax

Schedules use standard cron expression format:

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

Common Schedules

Cron	Description
0 9 * * *	Every day at 9:00 AM
0 9 * * 1	Every Monday at 9:00 AM
0 /6 * *	Every 6 hours
/15 * * *	Every 15 minutes
0 0 1 * *	First day of every month
0 9 * * 1-5	Weekdays at 9:00 AM

Timezone Configuration

Specify a timezone for your schedule:

1relay
2  .workflow("morning-report")
3  .schedule("0 9 * * *", {
4    timezone: "America/New_York"
5  })
6  .step("report")
7  .with("openai:gpt-4o")
8  .prompt("Generate morning report")

If no timezone is specified, schedules run in UTC. Always specify a timezone for user-facing reports.

Scheduled Input Data

Provide static input data for scheduled runs:

1relay
2  .workflow("scheduled-sync")
3  .schedule("0 */2 * * *", {
4    input: {
5      source: "salesforce",
6      target: "bigquery",
7      incremental: true
8    }
9  })
10  .step("sync")
11  .with("openai:gpt-4o")
12  .prompt("Sync {{input.source}} to {{input.target}}")

Use Case Examples

Daily Digest

1relay
2  .workflow("email-digest")
3  .schedule("0 8 * * *", { timezone: "America/Los_Angeles" })
4  .step("gather-news")
5  .with("openai:gpt-4o")
6  .prompt("Gather top news stories from yesterday")
7  .step("summarize")
8  .with("anthropic:claude-sonnet-4-20250514")
9  .depends("gather-news")
10  .prompt("Create email digest")

Weekly Report

1relay
2  .workflow("weekly-metrics")
3  .schedule("0 9 * * 1")  // Monday at 9 AM
4  .step("analyze")
5  .with("openai:gpt-4o")
6  .prompt("Analyze last week's metrics")
7  .step("report")
8  .with("anthropic:claude-sonnet-4-20250514")
9  .depends("analyze")
10  .prompt("Generate executive summary")

Hourly Monitoring

1relay
2  .workflow("health-check")
3  .schedule("0 * * * *")  // Every hour
4  .step("check")
5  .with("openai:gpt-4o-mini")
6  .prompt("Check system health status")
7  .step("alert", {
8    condition: "steps.check.output.status !== 'healthy'"
9  })
10  .with("openai:gpt-4o")
11  .depends("check")
12  .prompt("Generate alert message")

Managing Schedules

1# List all schedules
2npx relay schedules list
3
4# Pause a schedule
5npx relay schedules pause daily-summary
6
7# Resume a schedule
8npx relay schedules resume daily-summary
9
10# Delete a schedule
11npx relay schedules delete daily-summary
12
13# Trigger manually (for testing)
14npx relay schedules trigger daily-summary