Python SDKFeature Clients

Scheduled ClientPython SDK

Bases: BaseRestClient

The scheduled client is a client for managing scheduled workflows within Hatchet.

Methods:

NameDescription
aio_bulk_deleteBulk delete scheduled workflow runs.
aio_bulk_updateBulk reschedule scheduled workflow runs.
aio_createCreates a new scheduled workflow run.
aio_deleteDeletes a scheduled workflow run by its ID.
aio_getRetrieves a specific scheduled workflow by scheduled run trigger ID.
aio_listRetrieves a list of scheduled workflows based on provided filters.
aio_updateReschedule a scheduled workflow run by its ID.
bulk_deleteBulk delete scheduled workflow runs.
bulk_updateBulk reschedule scheduled workflow runs.
createCreates a new scheduled workflow run.
deleteDeletes a scheduled workflow run by its ID.
getRetrieves a specific scheduled workflow by scheduled run trigger ID.
listRetrieves a list of scheduled workflows based on provided filters.
updateReschedule a scheduled workflow run by its ID.

Functions

aio_bulk_delete

Bulk delete scheduled workflow runs.

Parameters:

NameTypeDescriptionDefault
scheduled_idslist[str] | NoneExplicit list of scheduled workflow run IDs to delete.None
workflow_idstr | NoneFilter by workflow ID.None
parent_workflow_run_idstr | NoneFilter by parent workflow run ID.None
parent_task_run_idstr | NoneFilter by the ID of the parent task run.None
additional_metadataJSONSerializableMapping | NoneFilter by additional metadata key/value pairs.None

Returns:

TypeDescription
ScheduledWorkflowsBulkDeleteResponseThe bulk delete response containing deleted IDs and per-item errors.

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:

NameTypeDescriptionDefault
workflow_namestrThe name of the workflow to schedule.required
trigger_atdatetimeThe datetime when the run should be triggered.required
inputJSONSerializableMappingThe input data for the scheduled workflow.required
additional_metadataJSONSerializableMappingAdditional metadata associated with the future run as a key-value pair.required

Returns:

TypeDescription
ScheduledRunThe created scheduled run.

aio_delete

Deletes a scheduled workflow run by its ID.

Parameters:

NameTypeDescriptionDefault
scheduled_idstrThe ID of the scheduled workflow run to delete.required

Returns:

TypeDescription
NoneNone

aio_get

Retrieves a specific scheduled workflow by scheduled run trigger ID.

Parameters:

NameTypeDescriptionDefault
scheduled_idstrThe scheduled workflow trigger ID to retrieve.required

Returns:

TypeDescription
ScheduledRunThe requested scheduled run.

aio_list

Retrieves a list of scheduled workflows based on provided filters.

Parameters:

NameTypeDescriptionDefault
offsetint | NoneThe offset to use in pagination.None
limitint | NoneThe maximum number of scheduled workflows to return.None
workflow_idstr | NoneThe ID of the workflow to filter by.None
parent_workflow_run_idstr | NoneThe ID of the parent workflow run to filter by.None
statuseslist[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED'] | Literal['SCHEDULED']] | NoneThe statuses of the triggered runs to filter by. SCHEDULED matches schedules that have not triggered a run yet.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to filter by.None
order_by_fieldLiteral['trigger_at', 'created_at'] | NoneThe field to order the results by.None
order_by_directionLiteral['asc', 'desc'] | NoneThe direction to order the results by.None

Returns:

TypeDescription
list[ScheduledRun]A list of scheduled runs matching the provided filters.

aio_update

Reschedule a scheduled workflow run by its ID.

Parameters:

NameTypeDescriptionDefault
scheduled_idstrThe ID of the scheduled workflow run to reschedule.required
trigger_atdatetimeThe datetime when the run should be triggered.required

Returns:

TypeDescription
ScheduledRunThe updated scheduled run.

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_task_run_id, additional_metadata)

Parameters:

NameTypeDescriptionDefault
scheduled_idslist[str] | NoneExplicit list of scheduled workflow run IDs to delete.None
workflow_idstr | NoneFilter by workflow ID.None
parent_workflow_run_idstr | NoneFilter by parent workflow run ID.None
parent_task_run_idstr | NoneFilter by the ID of the parent task run.None
additional_metadataJSONSerializableMapping | NoneFilter by additional metadata key/value pairs.None

Returns:

TypeDescription
ScheduledWorkflowsBulkDeleteResponseThe bulk delete response containing deleted IDs and per-item errors.

Raises:

TypeDescription
ValueErrorIf neither scheduled_ids nor any filter field is provided.

bulk_update

Bulk reschedule scheduled workflow runs.

Parameters:

NameTypeDescriptionDefault
updateslist[ScheduledWorkflowsBulkUpdateItem] | list[tuple[str, datetime]]Either: - a list of (scheduled_id, trigger_at) tuples, or - a list of ScheduledWorkflowsBulkUpdateItem objectsrequired

Returns:

TypeDescription
ScheduledWorkflowsBulkUpdateResponseThe 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:

NameTypeDescriptionDefault
workflow_namestrThe name of the workflow to schedule.required
trigger_atdatetimeThe datetime when the run should be triggered.required
inputJSONSerializableMappingThe input data for the scheduled workflow.required
additional_metadataJSONSerializableMappingAdditional metadata associated with the future run as a key-value pair.required

Returns:

TypeDescription
ScheduledRunThe created scheduled run.

delete

Deletes a scheduled workflow run by its ID.

Parameters:

NameTypeDescriptionDefault
scheduled_idstrThe ID of the scheduled workflow run to delete.required

Returns:

TypeDescription
NoneNone

get

Retrieves a specific scheduled workflow by scheduled run trigger ID.

Parameters:

NameTypeDescriptionDefault
scheduled_idstrThe scheduled workflow trigger ID to retrieve.required

Returns:

TypeDescription
ScheduledRunThe requested scheduled run.

list

Retrieves a list of scheduled workflows based on provided filters.

Parameters:

NameTypeDescriptionDefault
offsetint | NoneThe offset to use in pagination.None
limitint | NoneThe maximum number of scheduled workflows to return.None
workflow_idstr | NoneThe ID of the workflow to filter by.None
parent_workflow_run_idstr | NoneThe ID of the parent workflow run to filter by.None
statuseslist[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED'] | Literal['SCHEDULED']] | NoneThe statuses of the triggered runs to filter by. SCHEDULED matches schedules that have not triggered a run yet.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to filter by.None
order_by_fieldLiteral['trigger_at', 'created_at'] | NoneThe field to order the results by.None
order_by_directionLiteral['asc', 'desc'] | NoneThe direction to order the results by.None

Returns:

TypeDescription
list[ScheduledRun]A list of scheduled runs 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:

NameTypeDescriptionDefault
scheduled_idstrThe ID of the scheduled workflow run to reschedule.required
trigger_atdatetimeThe datetime when the run should be triggered.required

Returns:

TypeDescription
ScheduledRunThe updated scheduled run.

Last updated on November 13, 2026

On this page