We use cookies

We use cookies to ensure you get the best experience on our website. For more information on how we use cookies, please see our cookie policy.

By clicking "Accept", you agree to our use of cookies.
Learn more.

User GuideScheduled Trigger

Scheduled Runs

This example assumes we have a workflow registered on a running worker.

Scheduled runs allow you to trigger a workflow at a specific time in the future. Some example use cases of scheduling runs might include:

  • Sending a reminder email at a specific time after a user took an action.
  • Running a one-time maintenance task at a predetermined time as determined by your application. For instance, you might want to run a database vacuum during a maintenance window any time a task matches a certain criteria.
  • Allowing a customer to decide when they want your application to perform a specific task. For instance, if your application is a simple alarm app that sends a customer a notification at a time that they specify, you might create a scheduled run for each alarm that the customer sets.

Hatchet supports scheduled runs to run on a schedule defined in a few different ways:

  • Programmatically: Use the Hatchet SDKs to dynamically set the schedule of a workflow.
  • Hatchet Dashboard: Manually create scheduled runs from the Hatchet Dashboard.
⚠️

The scheduled time is when Hatchet enqueues the workflow, not when the run starts. Scheduling constraints like concurrency limits, rate limits, and retry policies can affect run start times.

Programmatically Creating Scheduled Runs

Create a Scheduled Run

You can create dynamic scheduled runs programmatically via the API to run workflows at a specific time in the future.

Here’s an example of creating a scheduled run to trigger a workflow tomorrow at noon:

schedule = simple.schedule([datetime(2025, 3, 14, 15, 9, 26)])
 
## do something with the id
 
print(schedule.id)
 

In this example you can have different scheduled times for different customers, or dynamically set the scheduled time based on some other business logic.

When creating a scheduled run via the API, you will receive a scheduled run object with a metadata property containing the id of the scheduled run. This id can be used to reference the scheduled run when deleting the scheduled run and is often stored in a database or other persistence layer.

Note: Be mindful of the time zone of the scheduled run. Scheduled runs are always stored and returned in UTC.

Deleting a Scheduled Run

You can delete a scheduled run by calling the delete method on the scheduled run object.

Listing Scheduled Runs

You can list all scheduled runs for a workflow by calling the list method on the scheduled run object.

Managing Scheduled Runs in the Hatchet Dashboard

In the Hatchet Dashboard, you can view and manage scheduled runs for your workflows.

Navigate to “Triggers” > “Scheduled Runs” in the left sidebar and click “Create Scheduled Run” at the top right.

You can specify run parameters such as Input, Additional Metadata, and the Scheduled Time.

Create Scheduled Run

Scheduled Run Considerations

When using scheduled runs, there are a few considerations to keep in mind:

  1. Time Zone: Scheduled runs are stored and returned in UTC. Make sure to consider the time zone when defining your scheduled time.

  2. Execution Time: The actual execution time of a scheduled run may vary slightly from the scheduled time. Hatchet makes a best-effort attempt to enqueue the workflow as close to the scheduled time as possible, but there may be slight delays due to system load or other factors.

  3. Missed Schedules: If a scheduled workflow is missed (e.g., due to system downtime), Hatchet will not automatically run the missed instances.

  4. Overlapping Schedules: If a workflow is still running when a second scheduled run is scheduled to start, Hatchet will start a new instance of the workflow or respect concurrency policy.