Recurring Runs with Cron

A Cron (opens in a new tab) is a time-based job scheduler that allows you to define when a workflow should be executed automatically. This feature is particularly useful for recurring tasks, such as daily data updates, weekly reports, or periodic maintenance jobs.

Hatchet supports cron triggers to run on a schedule defined in a few different ways:

Workflow Definitions: Define a cron expression in your workflow definition to trigger the workflow on a predefined schedule.
Dynamic Programmatically: Use the Hatchet SDKs to dynamically set the cron schedule of a workflow (i.e. customer defined schedule).
Hatchet Dashboard: Manually create cron triggers from the Hatchet Dashboard.

The expression 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.

Cron Expression Syntax

Cron expressions in Hatchet follow the standard cron syntax. A cron expression consists of five fields separated by spaces:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
* * * * *

Each field can contain a specific value, an asterisk (*) to represent all possible values, or a range of values. Here are some examples of cron expressions:

0 0 * * *: Run every day at midnight
*/15 * * * *: Run every 15 minutes
0 9 * * 1: Run every Monday at 9 AM
0 0 1 * *: Run on the first day of every month at midnight

Defining a Cron in Your Workflow Definition

You can define a workflow with a cron schedule by configuring the cron expression as part of the workflow definition:

examples/cron/workflow-definition.py

# Adding a cron trigger to a workflow is as simple
# as adding a `cron expression` to the `on_cron`
# prop of the workflow definition
@hatchet.workflow(on_crons=["* * * * *"])
class CronWorkflow:
    @hatchet.step()
    def step1(self, context: Context) -> dict[str, str]:
 
        return {
            "time": "step1",
        }

In the examples above, we set the on cron property of the workflows. The property specifies the cron expression that determines when the workflow should be triggered.

💡

Note: When modifying a cron in your workflow definition, it will override any cron schedule for previous crons defined in previous workflow definitions, but crons created via the API or Dashboard will still be respected.

Programmatically Creating Cron Triggers

Create a Cron Trigger

You can create dynamic cron triggers programmatically via the API. This is useful if you want to create a cron trigger that is not known at the time of workflow definition,

Here's an example of creating a a cron to trigger a report for a specific customer every day at noon:

examples/cron/programatic-sync.py

cron_trigger = hatchet.cron.create(
    workflow_name="simple-cron-workflow",
    cron_name="customer-a-daily-report",
    expression="0 12 * * *",
    input={
        "name": "John Doe",
    },
    additional_metadata={
        "customer_id": "customer-a",
    },
)
 
id = cron_trigger.metadata.id  # the id of the cron trigger

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

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

💡

Note: Cron Name and Expression are required fields when creating a cron trigger and we enforce a unique constraint on the two.

Delete a Cron Trigger

You can delete a cron trigger by passing the cron object or a cron trigger id to the delete method.

examples/cron/programatic-sync.py

hatchet.cron.delete(cron_trigger=cron_trigger.metadata.id)

💡

Note: Deleting a cron trigger will not cancel any currently running instances of the workflow. It will simply stop the cron trigger from triggering the workflow again.

List Cron Triggers

Retrieves a list of all workflow cron triggers matching the criteria.

examples/cron/programatic-sync.py

cron_triggers = hatchet.cron.list()

Managing Cron Triggers in the Hatchet Dashboard

In the Hatchet Dashboard, you can view and manage cron triggers for your workflows.

Navigate to "Triggers" > "Cron Jobs" in the left sidebar and click "Create Cron Job" at the top right.

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

Create Cron Job

Cron Considerations

When using cron triggers, there are a few considerations to keep in mind:

Time Zone: Cron schedules are UTC. Make sure to consider the time zone when defining your cron expressions.
Execution Time: The actual execution time of a cron-triggered workflow 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. It will wait for the next scheduled time to trigger the workflow.
Overlapping Schedules: If a workflow is still running when the next scheduled time arrives, Hatchet will start a new instance of the workflow or respect concurrency policy.

Event Trigger Schedule Trigger