Scheduled Client
Bases: BaseRestClient
The scheduled client is a client for managing scheduled workflows within Hatchet.
Methods:
| Name | Description |
|---|---|
aio_bulk_delete | Bulk delete scheduled workflow runs. |
aio_bulk_update | Bulk reschedule scheduled workflow runs. |
aio_create | Creates a new scheduled workflow run. |
aio_delete | Deletes a scheduled workflow run by its ID. |
aio_get | Retrieves a specific scheduled workflow by scheduled run trigger ID. |
aio_list | Retrieves a list of scheduled workflows based on provided filters. |
aio_update | Reschedule a scheduled workflow run by its ID. |
bulk_delete | Bulk delete scheduled workflow runs. |
bulk_update | Bulk reschedule scheduled workflow runs. |
create | Creates a new scheduled workflow run. |
delete | Deletes a scheduled workflow run by its ID. |
get | Retrieves a specific scheduled workflow by scheduled run trigger ID. |
list | Retrieves a list of scheduled workflows based on provided filters. |
update | Reschedule a scheduled workflow run by its ID. |
Functions
aio_bulk_delete
Bulk delete scheduled workflow runs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_ids | list[str] | None | Explicit list of scheduled workflow run IDs to delete. | None |
workflow_id | str | None | Filter by workflow ID. | None |
parent_workflow_run_id | str | None | Filter by parent workflow run ID. | None |
parent_step_run_id | str | None | Filter by parent step run ID. | None |
statuses | list[ScheduledRunStatus] | None | Filter by scheduled run statuses. | None |
additional_metadata | JSONSerializableMapping | None | Filter by additional metadata key/value pairs. | None |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflowsBulkDeleteResponse | The bulk delete response containing deleted IDs and per-item errors. |
Raises:
| Type | Description |
|---|---|
ValueError | If neither scheduled_ids nor any filter field is provided. |
aio_bulk_update
Bulk reschedule scheduled workflow runs.
See bulk_update for parameter details.
aio_create
Creates a new scheduled workflow run.
IMPORTANT: It's preferable to use Workflow.run (and similar) to trigger workflows if possible. This method is intended to be an escape hatch. For more details, see the documentation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_name | str | The name of the workflow to schedule. | required |
trigger_at | datetime | The datetime when the run should be triggered. | required |
input | JSONSerializableMapping | The input data for the scheduled workflow. | required |
additional_metadata | JSONSerializableMapping | Additional metadata associated with the future run as a key-value pair. | required |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflows | The created scheduled workflow instance. |
aio_delete
Deletes a scheduled workflow run by its ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | str | The ID of the scheduled workflow run to delete. | required |
Returns:
| Type | Description |
|---|---|
None | None |
aio_get
Retrieves a specific scheduled workflow by scheduled run trigger ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | str | The scheduled workflow trigger ID to retrieve. | required |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflows | The requested scheduled workflow instance. |
aio_list
Retrieves a list of scheduled workflows based on provided filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset | int | None | The offset to use in pagination. | None |
limit | int | None | The maximum number of scheduled workflows to return. | None |
workflow_id | str | None | The ID of the workflow to filter by. | None |
parent_workflow_run_id | str | None | The ID of the parent workflow run to filter by. | None |
statuses | list[ScheduledRunStatus] | None | A list of statuses to filter by. | None |
additional_metadata | JSONSerializableMapping | None | Additional metadata to filter by. | None |
order_by_field | ScheduledWorkflowsOrderByField | None | The field to order the results by. | None |
order_by_direction | WorkflowRunOrderByDirection | None | The direction to order the results by. | None |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflowsList | A list of scheduled workflows matching the provided filters. |
aio_update
Reschedule a scheduled workflow run by its ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | str | The ID of the scheduled workflow run to reschedule. | required |
trigger_at | datetime | The datetime when the run should be triggered. | required |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflows | The updated scheduled workflow instance. |
bulk_delete
Bulk delete scheduled workflow runs.
Provide either:
scheduled_ids(explicit list of scheduled run IDs), or- one or more filter fields (
workflow_id,parent_workflow_run_id,parent_step_run_id,statuses,additional_metadata)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_ids | list[str] | None | Explicit list of scheduled workflow run IDs to delete. | None |
workflow_id | str | None | Filter by workflow ID. | None |
parent_workflow_run_id | str | None | Filter by parent workflow run ID. | None |
parent_step_run_id | str | None | Filter by parent step run ID. | None |
statuses | list[ScheduledRunStatus] | None | Filter by scheduled run statuses. | None |
additional_metadata | JSONSerializableMapping | None | Filter by additional metadata key/value pairs. | None |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflowsBulkDeleteResponse | The bulk delete response containing deleted IDs and per-item errors. |
Raises:
| Type | Description |
|---|---|
ValueError | If neither scheduled_ids nor any filter field is provided. |
bulk_update
Bulk reschedule scheduled workflow runs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
updates | list[ScheduledWorkflowsBulkUpdateItem] | list[tuple[str, datetime]] | Either: - a list of (scheduled_id, trigger_at) tuples, or - a list of ScheduledWorkflowsBulkUpdateItem objects | required |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflowsBulkUpdateResponse | The bulk update response containing updated IDs and per-item errors. |
create
Creates a new scheduled workflow run.
IMPORTANT: It's preferable to use Workflow.run (and similar) to trigger workflows if possible. This method is intended to be an escape hatch. For more details, see the documentation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_name | str | The name of the workflow to schedule. | required |
trigger_at | datetime | The datetime when the run should be triggered. | required |
input | JSONSerializableMapping | The input data for the scheduled workflow. | required |
additional_metadata | JSONSerializableMapping | Additional metadata associated with the future run as a key-value pair. | required |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflows | The created scheduled workflow instance. |
delete
Deletes a scheduled workflow run by its ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | str | The ID of the scheduled workflow run to delete. | required |
Returns:
| Type | Description |
|---|---|
None | None |
get
Retrieves a specific scheduled workflow by scheduled run trigger ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | str | The scheduled workflow trigger ID to retrieve. | required |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflows | The requested scheduled workflow instance. |
list
Retrieves a list of scheduled workflows based on provided filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset | int | None | The offset to use in pagination. | None |
limit | int | None | The maximum number of scheduled workflows to return. | None |
workflow_id | str | None | The ID of the workflow to filter by. | None |
parent_workflow_run_id | str | None | The ID of the parent workflow run to filter by. | None |
statuses | list[ScheduledRunStatus] | None | A list of statuses to filter by. | None |
additional_metadata | JSONSerializableMapping | None | Additional metadata to filter by. | None |
order_by_field | ScheduledWorkflowsOrderByField | None | The field to order the results by. | None |
order_by_direction | WorkflowRunOrderByDirection | None | The direction to order the results by. | None |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflowsList | A list of scheduled workflows matching the provided filters. |
update
Reschedule a scheduled workflow run by its ID.
Note: the server may reject rescheduling if the scheduled run has already triggered, or if it was created via code definition (not via API).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | str | The ID of the scheduled workflow run to reschedule. | required |
trigger_at | datetime | The datetime when the run should be triggered. | required |
Returns:
| Type | Description |
|---|---|
ScheduledWorkflows | The updated scheduled workflow instance. |
Last updated on September 1, 2026