Skip to content
Cloudflare Docs
Workers
Cloudflare Docs
Workers
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)

ScheduledEvent

Background

A ScheduledEvent is the event type for scheduled requests to a Worker. It is the Object passed through as the event when a Worker is invoked by a Worker's Cron Trigger. ScheduledEvent is supported in Workers written with Service Worker syntax and Module Worker syntax.

Syntax: Service Worker

A ScheduledEvent can be handled in Workers functions written using the Service Worker syntax by attaching to the scheduled event with addEventListener:

addEventListener("scheduled", event => {
  event.waitUntil(handleScheduled(event))
})

Properties

  • event.cron string

    • The value of the Cron Trigger that started the ScheduledEvent.

  • event.type string

    • The type of event. This will always return "scheduled".

  • event.scheduledTime number

    • The time the ScheduledEvent was scheduled to be executed in milliseconds since January 1, 1970, UTC. It can be parsed as new Date(event.scheduledTime)

Methods

When a Workers script is invoked by a Cron Trigger, the Workers runtime starts a ScheduledEvent which will be handled by the event listener registered for the type "scheduled". The event handler can invoke the following methods of the event object to control what happens next:

  • event.waitUntil(promisePromise) void
    • Use this method to notify the runtime to wait for asynchronous tasks (e.g. logging, analytics to third-party services, streaming and caching). The first event.waitUntil to fail will be observed and recorded as the status in the Cron Trigger Past Events table. Otherwise, it will be reported as a Success.

Syntax: Module Worker

A ScheduledEvent can be handled in Workers functions written using the Module Worker syntax by adding a scheduled function to your module's exported handlers:

export default {
  async scheduled(event, env, ctx) {
    ctx.waitUntil(doSomeTaskOnASchedule())
  }
}

Properties

  • event.cron string

    • The value of the Cron Trigger that started the ScheduledEvent.

  • event.type string

    • The type of event. This will always return "scheduled".

  • event.scheduledTime number

    • The time the ScheduledEvent was scheduled to be executed in milliseconds since January 1, 1970, UTC. It can be parsed as new Date(event.scheduledTime).

  • env object

    • An object containing the bindings associated with your Module Worker, such as KV namespaces and Durable Objects.

  • ctx object

    • An object containing the context associated with your Module Worker. Currently, this object just contains the waitUntil function.

Methods

When a Workers script is invoked by a Cron Trigger, the Workers runtime starts a ScheduledEvent which will be handled by the scheduled function in your Workers Module class. The ctx argument represents the context your function runs in, and contains the following methods to control what happens next:

  • ctx.waitUntil(promisePromise) void
    • Use this method to notify the runtime to wait for asynchronous tasks (e.g., logging, analytics to third-party services, streaming and caching). The first ctx.waitUntil to fail will be observed and recorded as the status in the Cron Trigger Past Events table. Otherwise, it will be reported as a Success.