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.
Scheduled Run Considerations
When using scheduled runs, there are a few considerations to keep in mind:
-
Time Zone: Scheduled runs are stored and returned in UTC. Make sure to consider the time zone when defining your scheduled time.
-
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.
-
Missed Schedules: If a scheduled workflow is missed (e.g., due to system downtime), Hatchet will not automatically run the missed instances.
-
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.