Sleep

Upstash Workflow provides a Sleep feature that allows you to pause workflow execution for specified durations without consuming compute resources.

This feature enables you to build time-based workflows, implement delays between steps, and create scheduled operations without the limitations of traditional serverless timeouts.

How Sleep Works

When you use context.sleep or context.sleepUntil in your workflow, Upstash Workflow automatically pauses execution and schedules the next step to run after the specified delay. This happens without keeping your serverless function running, making it cost-effective and reliable for long delays.

Important: Sleep durations have limits based on your pricing plan:

• Free: Maximum delay of 7 days
• Pay-as-you-go: Maximum delay of 1 year
• Fixed pricing: Custom delays (no limit)

Sleep Methods

Upstash Workflow provides two methods for implementing delays in your workflows:

1. context.sleep

Pauses workflow execution for a specified duration relative to the current time.

TypeScript

import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(async (context) => {
  const { userId } = context.requestPayload;

  // Send welcome email immediately
  await context.run("send-welcome-email", async () => {
    return await sendWelcomeEmail(userId);
  });

  // Wait for 3 days before sending follow-up
  await context.sleep("wait-for-follow-up", "3d");

  // Send follow-up email
  await context.run("send-follow-up-email", async () => {
    return await sendFollowUpEmail(userId);
  });
});

You can specify durations using human-readable strings:

• "10s" = 10 seconds
• "1m" = 1 minute
• "30m" = 30 minutes
• "2h" = 2 hours
• "1d" = 1 day
• "1w" = 1 week
• "1mo" = 1 month
• "1y" = 1 year

You can also use numeric values in seconds:

• 60 = 60 seconds (1 minute)
• 3600 = 3600 seconds (1 hour)
• 86400 = 86400 seconds (1 day)

2. context.sleepUntil

Pauses workflow execution until a specific timestamp in the future.

TypeScript

import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(async (context) => {
  const { userId, scheduledTime } = context.requestPayload;

  // Calculate the scheduled time
  const scheduledDate = new Date(scheduledTime);

  // Wait until the scheduled time
  await context.sleepUntil("wait-until-scheduled", scheduledDate);

  // Execute the scheduled task
  await context.run("execute-scheduled-task", async () => {
    return await executeTask(userId);
  });
});

For context.sleepUntil, you can use:

• Date objects (JavaScript/TypeScript)
• Unix timestamps (Python)
• ISO string dates

Sleep operations have a precision of approximately 1 second. Very short delays (less than 1 second) may not be exact.

The sleep feature in Upstash Workflow provides a powerful way to create time-based, reliable workflows without the limitations of traditional serverless timeouts.

By leveraging this feature, you can build sophisticated business logic that spans hours, days, or even months while maintaining cost efficiency and reliability.