Skip to content
Cloudflare Docs

Schedule tasks

Schedule tasks to run in the future — whether that is seconds from now, at a specific date/time, or on a recurring cron schedule. Scheduled tasks survive agent restarts and are persisted to SQLite.

Scheduled tasks can do anything a request or message from a user can: make requests, query databases, send emails, read and write state. Scheduled tasks can invoke any regular method on your Agent.

Overview

The scheduling system supports four modes:

ModeSyntaxUse case
Delayedthis.schedule(60, ...)Run in 60 seconds
Scheduledthis.schedule(new Date(...), ...)Run at specific time
Cronthis.schedule("0 8 * * *", ...)Run on recurring schedule
Intervalthis.scheduleEvery(30, ...)Run every 30 seconds

Under the hood, scheduling uses Durable Object alarms to wake the agent at the right time. Tasks are stored in a SQLite table and executed in order.

Quick start

JavaScript
import { Agent } from "agents";


export class ReminderAgent extends Agent {
  async onRequest(request) {
    const url = new URL(request.url);


    // Schedule in 30 seconds
    await this.schedule(30, "sendReminder", {
      message: "Check your email",
    });


    // Schedule at specific time
    await this.schedule(new Date("2025-02-01T09:00:00Z"), "sendReminder", {
      message: "Monthly report due",
    });


    // Schedule recurring (every day at 8am)
    await this.schedule("0 8 * * *", "dailyDigest", {
      userId: url.searchParams.get("userId"),
    });


    return new Response("Scheduled!");
  }


  async sendReminder(payload) {
    console.log(`Reminder: ${payload.message}`);
    // Send notification, email, etc.
  }


  async dailyDigest(payload) {
    console.log(`Sending daily digest to ${payload.userId}`);
    // Generate and send digest
  }
}

Scheduling modes

Delayed execution

Pass a number to schedule a task to run after a delay in seconds:

JavaScript
// Run in 10 seconds
await this.schedule(10, "processTask", { taskId: "123" });


// Run in 5 minutes (300 seconds)
await this.schedule(300, "sendFollowUp", { email: "user@example.com" });


// Run in 1 hour
await this.schedule(3600, "checkStatus", { orderId: "abc" });

Use cases:

  • Debouncing rapid events
  • Delayed notifications ("You left items in your cart")
  • Retry with backoff
  • Rate limiting

Scheduled execution

Pass a Date object to schedule a task at a specific time:

JavaScript
// Run tomorrow at noon
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(12, 0, 0, 0);
await this.schedule(tomorrow, "sendReminder", { message: "Meeting time!" });


// Run at a specific timestamp
await this.schedule(new Date("2025-06-15T14:30:00Z"), "triggerEvent", {
  eventId: "conference-2025",
});


// Run in 2 hours using Date math
const twoHoursFromNow = new Date(Date.now() + 2 * 60 * 60 * 1000);
await this.schedule(twoHoursFromNow, "checkIn", {});

Use cases:

  • Appointment reminders
  • Deadline notifications
  • Scheduled content publishing
  • Time-based triggers

Recurring (cron)

Pass a cron expression string for recurring schedules:

JavaScript
// Every day at 8:00 AM
await this.schedule("0 8 * * *", "dailyReport", {});


// Every hour
await this.schedule("0 * * * *", "hourlyCheck", {});


// Every Monday at 9:00 AM
await this.schedule("0 9 * * 1", "weeklySync", {});


// Every 15 minutes
await this.schedule("*/15 * * * *", "pollForUpdates", {});


// First day of every month at midnight
await this.schedule("0 0 1 * *", "monthlyCleanup", {});

Cron syntax: minute hour day month weekday

FieldValuesSpecial characters
Minute0-59* , - /
Hour0-23* , - /
Day of Month1-31* , - /
Month1-12* , - /
Day of Week0-6 (0=Sunday)* , - /

Common patterns:

JavaScript
"* * * * *"; // Every minute
"*/5 * * * *"; // Every 5 minutes
"0 * * * *"; // Every hour (on the hour)
"0 0 * * *"; // Every day at midnight
"0 8 * * 1-5"; // Weekdays at 8am
"0 0 * * 0"; // Every Sunday at midnight
"0 0 1 * *"; // First of every month

Use cases:

  • Daily/weekly reports
  • Periodic cleanup jobs
  • Polling external services
  • Health checks
  • Subscription renewals

Interval

Use scheduleEvery() to run a task at fixed intervals (in seconds). Unlike cron, intervals support sub-minute precision and arbitrary durations:

JavaScript
// Poll every 30 seconds
await this.scheduleEvery(30, "poll", { source: "api" });


// Health check every 45 seconds
await this.scheduleEvery(45, "healthCheck", {});


// Sync every 90 seconds (1.5 minutes - cannot be expressed in cron)
await this.scheduleEvery(90, "syncData", { destination: "warehouse" });

Key differences from cron:

FeatureCronInterval
Minimum granularity1 minute1 second
Arbitrary intervalsNo (must fit cron pattern)Yes
Fixed scheduleYes (for example, "every day at 8am")No (relative to start)
Overlap preventionNoYes (built-in)

Overlap prevention:

If a callback takes longer than the interval, the next execution is skipped (not queued). This prevents runaway resource usage:

JavaScript
class PollingAgent extends Agent {
  async poll() {
    // If this takes 45 seconds and interval is 30 seconds,
    // the next poll is skipped (with a warning logged)
    const data = await slowExternalApi();
    await this.processData(data);
  }
}


// Set up 30-second interval
await this.scheduleEvery(30, "poll", {});

When a skip occurs, you will see a warning in logs:

Skipping interval schedule abc123: previous execution still running

Error resilience:

If the callback throws an error, the interval continues — only that execution fails:

JavaScript
class SyncAgent extends Agent {
  async syncData() {
    // Even if this throws, the interval keeps running
    const response = await fetch("https://api.example.com/data");
    if (!response.ok) throw new Error("Sync failed");
    // ...
  }
}

Use cases:

  • Sub-minute polling (every 10, 30, 45 seconds)
  • Intervals that do not map to cron (every 90 seconds, every 7 minutes)
  • Rate-limited API polling with precise control
  • Real-time data synchronization

Managing scheduled tasks

Get a schedule

Retrieve a scheduled task by its ID:

JavaScript
const schedule = this.getSchedule(scheduleId);


if (schedule) {
  console.log(
    `Task ${schedule.id} will run at ${new Date(schedule.time * 1000)}`,
  );
  console.log(`Callback: ${schedule.callback}`);
  console.log(`Type: ${schedule.type}`); // "scheduled" | "delayed" | "cron" | "interval"
} else {
  console.log("Schedule not found");
}

List schedules

Query scheduled tasks with optional filters:

JavaScript
// Get all scheduled tasks
const allSchedules = this.getSchedules();


// Get only cron jobs
const cronJobs = this.getSchedules({ type: "cron" });


// Get tasks in the next hour
const upcoming = this.getSchedules({
  timeRange: {
    start: new Date(),
    end: new Date(Date.now() + 60 * 60 * 1000),
  },
});


// Get a specific task by ID
const specific = this.getSchedules({ id: "abc123" });


// Combine filters
const upcomingCronJobs = this.getSchedules({
  type: "cron",
  timeRange: {
    start: new Date(),
    end: new Date(Date.now() + 24 * 60 * 60 * 1000),
  },
});

Cancel a schedule

Remove a scheduled task before it executes:

JavaScript
const cancelled = await this.cancelSchedule(scheduleId);


if (cancelled) {
  console.log("Schedule cancelled successfully");
} else {
  console.log("Schedule not found (may have already executed)");
}

Example: Cancellable reminders

JavaScript
class ReminderAgent extends Agent {
  async setReminder(userId, message, delaySeconds) {
    const schedule = await this.schedule(delaySeconds, "sendReminder", {
      userId,
      message,
    });


    // Store the schedule ID so user can cancel later
    this.sql`
      INSERT INTO user_reminders (user_id, schedule_id, message)
      VALUES (${userId}, ${schedule.id}, ${message})
    `;


    return schedule.id;
  }


  async cancelReminder(scheduleId) {
    const cancelled = await this.cancelSchedule(scheduleId);


    if (cancelled) {
      this.sql`DELETE FROM user_reminders WHERE schedule_id = ${scheduleId}`;
    }


    return cancelled;
  }


  async sendReminder(payload) {
    // Send the reminder...


    // Clean up the record
    this.sql`DELETE FROM user_reminders WHERE user_id = ${payload.userId}`;
  }
}

The Schedule object

When you create or retrieve a schedule, you get a Schedule object:

TypeScript
type Schedule<T> = {
  id: string; // Unique identifier
  callback: string; // Method name to call
  payload: T; // Data passed to the callback
  time: number; // Unix timestamp (seconds) of next execution
} & (
  | { type: "scheduled" } // One-time at specific date
  | { type: "delayed"; delayInSeconds: number } // One-time after delay
  | { type: "cron"; cron: string } // Recurring (cron expression)
  | { type: "interval"; intervalSeconds: number } // Recurring (fixed interval)
);

Example:

JavaScript
const schedule = await this.schedule(60, "myTask", { foo: "bar" });


console.log(schedule);
// {
//   id: "abc123xyz",
//   callback: "myTask",
//   payload: { foo: "bar" },
//   time: 1706745600,
//   type: "delayed",
//   delayInSeconds: 60
// }

Patterns

Rescheduling from callbacks

For dynamic recurring schedules, schedule the next run from within the callback:

JavaScript
class PollingAgent extends Agent {
  async startPolling(intervalSeconds) {
    await this.schedule(intervalSeconds, "poll", { interval: intervalSeconds });
  }


  async poll(payload) {
    try {
      const data = await fetch("https://api.example.com/updates");
      await this.processUpdates(await data.json());
    } catch (error) {
      console.error("Polling failed:", error);
    }


    // Schedule the next poll (regardless of success/failure)
    await this.schedule(payload.interval, "poll", payload);
  }


  async stopPolling() {
    // Cancel all polling schedules
    const schedules = this.getSchedules({ type: "delayed" });
    for (const schedule of schedules) {
      if (schedule.callback === "poll") {
        await this.cancelSchedule(schedule.id);
      }
    }
  }
}

Exponential backoff retry

JavaScript
class RetryAgent extends Agent {
  async attemptTask(payload) {
    try {
      await this.doWork(payload.taskId);
      console.log(
        `Task ${payload.taskId} succeeded on attempt ${payload.attempt}`,
      );
    } catch (error) {
      if (payload.attempt >= payload.maxAttempts) {
        console.error(
          `Task ${payload.taskId} failed after ${payload.maxAttempts} attempts`,
        );
        return;
      }


      // Exponential backoff: 2^attempt seconds (2s, 4s, 8s, 16s...)
      const delaySeconds = Math.pow(2, payload.attempt);


      await this.schedule(delaySeconds, "attemptTask", {
        ...payload,
        attempt: payload.attempt + 1,
      });


      console.log(`Retrying task ${payload.taskId} in ${delaySeconds}s`);
    }
  }


  async doWork(taskId) {
    // Your actual work here
  }
}

Self-destructing agents

You can safely call this.destroy() from within a scheduled callback:

JavaScript
class TemporaryAgent extends Agent {
  async onStart() {
    // Self-destruct in 24 hours
    await this.schedule(24 * 60 * 60, "cleanup", {});
  }


  async cleanup() {
    // Perform final cleanup
    console.log("Agent lifetime expired, cleaning up...");


    // This is safe to call from a scheduled callback
    await this.destroy();
  }
}

AI-assisted scheduling

The SDK includes utilities for parsing natural language scheduling requests with AI.

getSchedulePrompt()

Returns a system prompt for parsing natural language into scheduling parameters:

JavaScript
import { getSchedulePrompt, scheduleSchema } from "agents";
import { generateObject } from "ai";
import { openai } from "@ai-sdk/openai";


class SmartScheduler extends Agent {
  async parseScheduleRequest(userInput) {
    const result = await generateObject({
      model: openai("gpt-4o"),
      system: getSchedulePrompt({ date: new Date() }),
      prompt: userInput,
      schema: scheduleSchema,
    });


    return result.object;
  }


  async handleUserRequest(input) {
    // Parse: "remind me to call mom tomorrow at 3pm"
    const parsed = await this.parseScheduleRequest(input);


    // parsed = {
    //   description: "call mom",
    //   when: {
    //     type: "scheduled",
    //     date: "2025-01-30T15:00:00Z"
    //   }
    // }


    if (parsed.when.type === "scheduled" && parsed.when.date) {
      await this.schedule(new Date(parsed.when.date), "sendReminder", {
        message: parsed.description,
      });
    } else if (parsed.when.type === "delayed" && parsed.when.delayInSeconds) {
      await this.schedule(parsed.when.delayInSeconds, "sendReminder", {
        message: parsed.description,
      });
    } else if (parsed.when.type === "cron" && parsed.when.cron) {
      await this.schedule(parsed.when.cron, "sendReminder", {
        message: parsed.description,
      });
    }
  }


  async sendReminder(payload) {
    console.log(`Reminder: ${payload.message}`);
  }
}

scheduleSchema

A Zod schema for validating parsed scheduling data. Uses a discriminated union on when.type so each variant only contains the fields it needs:

JavaScript
import { scheduleSchema } from "agents";


// The schema is a discriminated union:
// {
//   description: string,
//   when:
//     | { type: "scheduled", date: string }       // ISO 8601 date string
//     | { type: "delayed", delayInSeconds: number }
//     | { type: "cron", cron: string }
//     | { type: "no-schedule" }
// }

Scheduling vs Queue vs Workflows

FeatureQueueSchedulingWorkflows
WhenImmediately (FIFO)Future timeFuture time
ExecutionSequentialAt scheduled timeMulti-step
RetriesBuilt-inBuilt-inAutomatic
PersistenceSQLiteSQLiteWorkflow engine
RecurringNoYes (cron)No (use scheduling)
Complex logicNoNoYes
Human approvalNoNoYes

Use Queue when:

  • You need background processing without blocking the response
  • Tasks should run ASAP but do not need to block
  • Order matters (FIFO)

Use Scheduling when:

  • Tasks need to run at a specific time
  • You need recurring jobs (cron)
  • Delayed execution (debouncing, retries)

Use Workflows when:

  • Multi-step processes with dependencies
  • Automatic retries with backoff
  • Human-in-the-loop approvals
  • Long-running tasks (minutes to hours)

API reference

schedule()

TypeScript
async schedule<T>(
  when: Date | string | number,
  callback: keyof this,
  payload?: T,
  options?: { retry?: RetryOptions }
): Promise<Schedule<T>>

Schedule a task for future execution.

Parameters:

  • when - When to execute: number (seconds delay), Date (specific time), or string (cron expression)
  • callback - Name of the method to call
  • payload - Data to pass to the callback (must be JSON-serializable)
  • options.retry - Optional retry configuration. Refer to Retries for details.

Returns: A Schedule object with the task details

scheduleEvery()

TypeScript
async scheduleEvery<T>(
  intervalSeconds: number,
  callback: keyof this,
  payload?: T,
  options?: { retry?: RetryOptions }
): Promise<Schedule<T>>

Schedule a task to run repeatedly at a fixed interval.

Parameters:

  • intervalSeconds - Number of seconds between executions (must be greater than 0)
  • callback - Name of the method to call
  • payload - Data to pass to the callback (must be JSON-serializable)
  • options.retry - Optional retry configuration. Refer to Retries for details.

Returns: A Schedule object with type: "interval"

Behavior:

  • First execution occurs after intervalSeconds (not immediately)
  • If callback is still running when next execution is due, it is skipped (overlap prevention)
  • If callback throws an error, the interval continues
  • Cancel with cancelSchedule(id) to stop the entire interval

getSchedule()

TypeScript
getSchedule<T>(id: string): Schedule<T> | undefined

Get a scheduled task by ID. Returns undefined if not found. This method is synchronous.

getSchedules()

TypeScript
getSchedules<T>(criteria?: {
  id?: string;
  type?: "scheduled" | "delayed" | "cron" | "interval";
  timeRange?: { start?: Date; end?: Date };
}): Schedule<T>[]

Get scheduled tasks matching the criteria. This method is synchronous.

cancelSchedule()

TypeScript
async cancelSchedule(id: string): Promise<boolean>

Cancel a scheduled task. Returns true if cancelled, false if not found.

keepAlive()

TypeScript
async keepAlive(): Promise<() => void>

Prevent the Durable Object from being evicted due to inactivity by creating a 30-second heartbeat schedule. Returns a disposer function that cancels the heartbeat when called. The disposer is idempotent — calling it multiple times is safe.

Always call the disposer when the work is done — otherwise the heartbeat continues indefinitely.

JavaScript
const dispose = await this.keepAlive();
try {
  // Long-running work that must not be interrupted
  const result = await longRunningComputation();
  await sendResults(result);
} finally {
  dispose();
}

keepAliveWhile()

TypeScript
async keepAliveWhile<T>(fn: () => Promise<T>): Promise<T>

Run an async function while keeping the Durable Object alive. The heartbeat is automatically started before the function runs and stopped when it completes (whether it succeeds or throws). Returns the value returned by the function.

This is the recommended way to use keepAlive — it guarantees cleanup.

JavaScript
const result = await this.keepAliveWhile(async () => {
  const data = await longRunningComputation();
  return data;
});

Keeping the agent alive

Durable Objects are evicted after a period of inactivity (typically 70-140 seconds with no incoming requests, WebSocket messages, or alarms). During long-running operations — streaming LLM responses, waiting on external APIs, running multi-step computations — the agent can be evicted mid-flight.

keepAlive() prevents this by creating a 30-second heartbeat schedule. The internal heartbeat callback is a no-op — the alarm firing itself is what resets the inactivity timer. Because it uses the scheduling system:

  • The heartbeat does not conflict with your own schedules (the scheduling system multiplexes through a single alarm slot)
  • The heartbeat shows up in getSchedules() if you need to inspect it
  • Multiple concurrent keepAlive() calls each get their own schedule, so they do not interfere with each other

Multiple concurrent callers

Each keepAlive() call returns an independent disposer:

JavaScript
const dispose1 = await this.keepAlive();
const dispose2 = await this.keepAlive();


// Both heartbeats are active
dispose1(); // Only cancels the first heartbeat
// Agent is still alive via dispose2's heartbeat


dispose2(); // Now the agent can go idle

AIChatAgent

AIChatAgent automatically calls keepAlive() during streaming responses. You do not need to add it yourself when using AIChatAgent — every LLM stream is protected from idle eviction by default.

When to use keepAlive

ScenarioUse keepAlive?
Streaming LLM responses via AIChatAgentNo — already built in
Long-running computation in a custom AgentYes
Waiting on a slow external API callYes
Multi-step tool executionYes
Short request-response handlersNo — not needed
Background work via scheduling or workflowsNo — alarms already keep the DO active

Limits

  • Maximum tasks: Limited by SQLite storage (each task is a row). Practical limit is tens of thousands per agent.
  • Task size: Each task (including payload) can be up to 2MB.
  • Minimum delay: 0 seconds (runs on next alarm tick)
  • Cron precision: Minute-level (not seconds)
  • Interval precision: Second-level
  • Cron jobs: After execution, automatically rescheduled for the next occurrence
  • Interval jobs: After execution, rescheduled for now + intervalSeconds; skipped if still running

Next steps

Queue tasks Immediate background task processing.
Run Workflows Durable multi-step background processing.
Agents API Complete API reference for the Agents SDK.