Scheduled Runs

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

Scheduled runs allow you to trigger a task 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 task.
• Hatchet Dashboard: Manually create scheduled runs from the Hatchet Dashboard.

Programmatically Creating Scheduled Runs

Create a Scheduled Run

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

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

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

const runAt = new Date(new Date().setHours(12, 0, 0, 0) + 24 * 60 * 60 * 1000);

const scheduled = await simple.schedule(runAt, {
  Message: 'hello',
});

// it may be helpful to store the scheduled run ID of the workflow
// in a database or other persistent storage for later use
const scheduledRunId = scheduled.metadata.id;
console.log(scheduledRunId);

// ... normal workflow definition
func main() {
	// ... initialize client, worker and workflow

	go func() {
		schedule, err := c.Schedule().Create(
			context.Background(),
			"schedule-workflow",
			&client.ScheduleOpts{
				TriggerAt: time.Now().UTC().Add(time.Minute),
				Input: map[string]interface{}{
					"message": "Hello, world!",
				},
				AdditionalMetadata: map[string]string{},
			},
		)

		if err != nil {
			panic(err)
		}

		fmt.Println(schedule.TriggerAt, schedule.WorkflowName)
	}()

	// ... wait for interrupt signal
}

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.

Deleting a Scheduled Run

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

hatchet.scheduled.delete(scheduled_id=scheduled_run.metadata.id)

🚨 No snippet found for Deleting a Scheduled Run 

/* eslint-disable no-console */
import { hatchet } from '../hatchet-client';
import { simple } from './workflow';

async function main() {
  // ❓ Create a Scheduled Run

  const runAt = new Date(new Date().setHours(12, 0, 0, 0) + 24 * 60 * 60 * 1000);

  const scheduled = await simple.schedule(runAt, {
    Message: 'hello',
  });

  // 👀 Get the scheduled run ID of the workflow
  // it may be helpful to store the scheduled run ID of the workflow
  // in a database or other persistent storage for later use
  const scheduledRunId = scheduled.metadata.id;
  console.log(scheduledRunId);
  // !!

  await hatchet.schedules.delete(scheduled);
}

if (require.main === module) {
  main();
}

err = c.Schedule().Delete(context.Background(), id)

Listing Scheduled Runs

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

scheduled_runs = hatchet.scheduled.list()

🚨 No snippet found for Listing Scheduled Runs 

/* eslint-disable no-console */
import { hatchet } from '../hatchet-client';
import { simple } from './workflow';

async function main() {
  // ❓ Create a Scheduled Run

  const runAt = new Date(new Date().setHours(12, 0, 0, 0) + 24 * 60 * 60 * 1000);

  const scheduled = await simple.schedule(runAt, {
    Message: 'hello',
  });

  // 👀 Get the scheduled run ID of the workflow
  // it may be helpful to store the scheduled run ID of the workflow
  // in a database or other persistent storage for later use
  const scheduledRunId = scheduled.metadata.id;
  console.log(scheduledRunId);
  // !!

  await hatchet.schedules.delete(scheduled);
}

if (require.main === module) {
  main();
}

schedules, err := c.Schedule().List(context.Background())

Managing Scheduled Runs in the Hatchet Dashboard

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

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:

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 task 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 task is missed (e.g., due to system downtime), Hatchet will not automatically run the missed instances when the service comes back online.

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