diff --git a/frontend/docs/pages/v1/scheduled-runs.mdx b/frontend/docs/pages/v1/scheduled-runs.mdx
index 08d202ec6..cd2880ca2 100644
--- a/frontend/docs/pages/v1/scheduled-runs.mdx
+++ b/frontend/docs/pages/v1/scheduled-runs.mdx
@@ -5,30 +5,21 @@ import UniversalTabs from "@/components/UniversalTabs";
# Scheduled Runs
-Scheduled runs allow you to trigger a task at a specific time in the future.
+Scheduled runs trigger a task at a specific point in the future. Common use cases include:
-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](/v1/scheduled-runs#programmatically-creating-scheduled-runs): Use the Hatchet SDKs to dynamically set the schedule of a task.
-- [Hatchet Dashboard](/v1/scheduled-runs#managing-scheduled-runs-in-the-hatchet-dashboard): Manually create scheduled runs from the Hatchet Dashboard.
+- Sending a reminder email after a user action.
+- Running a one-time maintenance task (e.g., a database vacuum) during a predetermined window.
+- Letting a customer specify when a task should run, such as setting an alarm.
The scheduled time is when Hatchet **enqueues** the task, not when the run
- starts. Scheduling constraints like concurrency limits, rate limits, and retry
- policies can affect run start times.
+ starts. Concurrency limits, rate limits, and retry policies can affect the
+ actual start time.
-### Create a Scheduled Run
+## 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:
+Scheduled runs can be created programmatically. This gives an option for the trigger time to differ per customer or be derived from application logic.
@@ -47,16 +38,13 @@ Here's an example of creating a scheduled run to trigger a task tomorrow at noon
-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.
+The API returns a scheduled run object whose ID should be persisted — it is required for subsequent delete or reschedule operations.
- Note: Be mindful of the time zone of the scheduled run. Scheduled runs are
- **always** stored and returned in UTC.
+ Scheduled runs are always stored and returned in UTC.
-### Deleting a Scheduled Run
+## Deleting a Scheduled Run
@@ -73,7 +61,7 @@ When creating a scheduled run via the API, you will receive a scheduled run obje
-### Listing Scheduled Runs
+## Listing Scheduled Runs
@@ -90,7 +78,7 @@ When creating a scheduled run via the API, you will receive a scheduled run obje
-### Rescheduling a Scheduled Run
+## Rescheduling a Scheduled Run
@@ -112,14 +100,14 @@ When creating a scheduled run via the API, you will receive a scheduled run obje
- You can only reschedule scheduled runs created via the API (not runs created
- via a code-defined schedule), and Hatchet may reject rescheduling if the run
- has already triggered.
+ Only scheduled runs created via the API can be rescheduled — not runs defined
+ in code. Hatchet will reject a reschedule request if the run has already
+ triggered.
-### Bulk operations (delete / reschedule)
+## Bulk Operations (Delete / Reschedule)
-Hatchet supports bulk operations for scheduled runs. You can bulk delete scheduled runs, and you can bulk reschedule scheduled runs by providing a list of updates.
+Hatchet supports bulk delete and bulk reschedule operations for scheduled runs.
@@ -144,14 +132,12 @@ Hatchet supports bulk operations for scheduled runs. You can bulk delete schedul
-## Scheduled Run Considerations
+## Considerations
-When using scheduled runs, there are a few considerations to keep in mind:
+1. **Time zone**: All scheduled run times are stored and returned in UTC.
-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**: Hatchet enqueues the task as close to the scheduled time as possible, but system load or other factors may introduce minor delays.
-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**: Hatchet does not replay missed runs after downtime. If a scheduled task is missed, it will not execute when the service recovers.
-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](/v1/concurrency) policy.
+4. **Overlapping runs**: If a prior run is still active when a new scheduled run triggers, Hatchet starts a new instance or applies the configured [concurrency](/v1/concurrency) policy.
diff --git a/frontend/docs/public/schedule-dash.gif b/frontend/docs/public/schedule-dash.gif
new file mode 100644
index 000000000..18fe41413
Binary files /dev/null and b/frontend/docs/public/schedule-dash.gif differ
diff --git a/sdks/python/examples/simple/schedule.py b/sdks/python/examples/simple/schedule.py
index 0a8b331ef..b0ac6811e 100644
--- a/sdks/python/examples/simple/schedule.py
+++ b/sdks/python/examples/simple/schedule.py
@@ -4,7 +4,9 @@ from examples.simple.worker import simple
# > Schedule a Task
-tomorrow_noon = datetime.now(tz=timezone.utc).replace(hour=12, minute=0, second=0, microsecond=0) + timedelta(days=1)
+tomorrow_noon = datetime.now(tz=timezone.utc).replace(
+ hour=12, minute=0, second=0, microsecond=0
+) + timedelta(days=1)
scheduled_run = simple.schedule(tomorrow_noon, input={"Message": "hello"})