Python SDKFeature Clients

Runs ClientPython SDK

Bases: BaseRestClient

The runs client is a client for interacting with task and workflow runs within Hatchet.

Methods:

NameDescription
getGet workflow run details for a given workflow run ID.
aio_getGet workflow run details for a given workflow run ID.
get_statusGet workflow run status for a given workflow run ID.
aio_get_statusGet workflow run status for a given workflow run ID.
listList task runs according to a set of filters, newest first.
aio_listList task runs according to a set of filters, newest first.
createTrigger a new workflow run.
aio_createTrigger a new workflow run.
replayReplay a task or workflow run.
aio_replayReplay a task or workflow run.
bulk_replayReplay task or workflow runs in bulk, according to a set of filters.
aio_bulk_replayReplay task or workflow runs in bulk, according to a set of filters.
cancelCancel a task or workflow run.
aio_cancelCancel a task or workflow run.
bulk_cancelCancel task or workflow runs in bulk, according to a set of filters.
aio_bulk_cancelCancel task or workflow runs in bulk, according to a set of filters.
get_resultGet the result of a workflow run by its external ID.
aio_get_resultGet the result of a workflow run by its external ID.
get_run_refGet a reference to a workflow run.
get_task_runGet task run details for a given task run ID.
aio_get_task_runGet task run details for a given task run ID.
aio_subscribe_to_streamSubscribe to the stream chunks sent by a run via ctx.put_stream.

Functions

get

Get workflow run details for a given workflow run ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the workflow run to retrieve details for.required

Returns:

TypeDescription
V1WorkflowRunDetailsWorkflow run details for the specified workflow run ID.

aio_get

Get workflow run details for a given workflow run ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the workflow run to retrieve details for.required

Returns:

TypeDescription
V1WorkflowRunDetailsWorkflow run details for the specified workflow run ID.

get_status

Get workflow run status for a given workflow run ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the workflow run to retrieve details for.required

Returns:

TypeDescription
Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']The task status

aio_get_status

Get workflow run status for a given workflow run ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the workflow run to retrieve details for.required

Returns:

TypeDescription
Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']The task status

list

List task runs according to a set of filters, newest first.

Parameters:

NameTypeDescriptionDefault
sincedatetime | NoneThe start time for filtering task runs.None
only_tasksboolWhether to only list task runs.False
offsetint | NoneThe number of task runs to skip, counted across the whole time range.None
limitint | NoneThe maximum number of task runs to return, counted across the whole time range. Returns every matching task run if not set.None
statuseslist[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']] | NoneThe statuses to filter task runs by.None
untildatetime | NoneThe end time for filtering task runs.None
additional_metadatadict[str, str] | NoneAdditional metadata to filter task runs by.None
workflow_idslist[str] | NoneThe workflow IDs to filter task runs by.None
worker_idstr | NoneThe worker ID to filter task runs by.None
parent_task_run_idstr | NoneThe ID of the parent task run to filter task runs by.None
triggering_event_idstr | NoneThe ID of the event that triggered the task run.None
include_payloadsboolWhether to include payloads in the response.True

Returns:

TypeDescription
list[TaskRunSummary]A list of task runs matching the specified filters.

aio_list

List task runs according to a set of filters, newest first.

Parameters:

NameTypeDescriptionDefault
sincedatetime | NoneThe start time for filtering task runs.None
only_tasksboolWhether to only list task runs.False
offsetint | NoneThe number of task runs to skip, counted across the whole time range.None
limitint | NoneThe maximum number of task runs to return, counted across the whole time range. Returns every matching task run if not set.None
statuseslist[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']] | NoneThe statuses to filter task runs by.None
untildatetime | NoneThe end time for filtering task runs.None
additional_metadatadict[str, str] | NoneAdditional metadata to filter task runs by.None
workflow_idslist[str] | NoneThe workflow IDs to filter task runs by.None
worker_idstr | NoneThe worker ID to filter task runs by.None
parent_task_run_idstr | NoneThe ID of the parent task run to filter task runs by.None
triggering_event_idstr | NoneThe ID of the event that triggered the task run.None
include_payloadsboolWhether to include payloads in the response.True

Returns:

TypeDescription
list[TaskRunSummary]A list of task runs matching the specified filters.

create

Trigger a new 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 trigger.required
inputJSONSerializableMappingThe input data for the workflow run.required
additional_metadataJSONSerializableMapping | NoneAdditional metadata associated with the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the workflow run.None

Returns:

TypeDescription
V1WorkflowRunDetailsThe details of the triggered workflow run.

aio_create

Trigger a new 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 trigger.required
inputJSONSerializableMappingThe input data for the workflow run.required
additional_metadataJSONSerializableMapping | NoneAdditional metadata associated with the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the workflow run.None

Returns:

TypeDescription
V1WorkflowRunDetailsThe details of the triggered workflow run.

replay

Replay a task or workflow run.

Parameters:

NameTypeDescriptionDefault
run_idstrThe external ID of the task or workflow run to replay.required

Returns:

TypeDescription
NoneNone

aio_replay

Replay a task or workflow run.

Parameters:

NameTypeDescriptionDefault
run_idstrThe external ID of the task or workflow run to replay.required

Returns:

TypeDescription
NoneNone

bulk_replay

Replay task or workflow runs in bulk, according to a set of filters.

Parameters:

NameTypeDescriptionDefault
optionsBulkCancelReplayOptionsOptions for bulk replay, including filters and IDs.required

Returns:

TypeDescription
NoneNone

aio_bulk_replay

Replay task or workflow runs in bulk, according to a set of filters.

Parameters:

NameTypeDescriptionDefault
optionsBulkCancelReplayOptionsOptions for bulk replay, including filters and IDs.required

Returns:

TypeDescription
NoneNone

cancel

Cancel a task or workflow run.

Parameters:

NameTypeDescriptionDefault
run_idstrThe external ID of the task or workflow run to cancel.required

Returns:

TypeDescription
NoneNone

aio_cancel

Cancel a task or workflow run.

Parameters:

NameTypeDescriptionDefault
run_idstrThe external ID of the task or workflow run to cancel.required

Returns:

TypeDescription
NoneNone

bulk_cancel

Cancel task or workflow runs in bulk, according to a set of filters.

Parameters:

NameTypeDescriptionDefault
optionsBulkCancelReplayOptionsOptions for bulk cancel, including filters and IDs.required

Returns:

TypeDescription
NoneNone

aio_bulk_cancel

Cancel task or workflow runs in bulk, according to a set of filters.

Parameters:

NameTypeDescriptionDefault
optionsBulkCancelReplayOptionsOptions for bulk cancel, including filters and IDs.required

Returns:

TypeDescription
NoneNone

get_result

Get the result of a workflow run by its external ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe external ID of the workflow run to retrieve the result for.required

Returns:

TypeDescription
JSONSerializableMappingThe result of the workflow run.

aio_get_result

Get the result of a workflow run by its external ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe external ID of the workflow run to retrieve the result for.required

Returns:

TypeDescription
JSONSerializableMappingThe result of the workflow run.

get_run_ref

Get a reference to a workflow run.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the workflow run to get a reference to.required

Returns:

TypeDescription
WorkflowRunRefA reference to the specified workflow run.

get_task_run

Get task run details for a given task run ID.

Parameters:

NameTypeDescriptionDefault
task_run_idstrThe ID of the task run to retrieve details for.required

Returns:

TypeDescription
TaskRunSummaryTask run details for the specified task run ID.

aio_get_task_run

Get task run details for a given task run ID.

Parameters:

NameTypeDescriptionDefault
task_run_idstrThe ID of the task run to retrieve details for.required

Returns:

TypeDescription
TaskRunSummaryTask run details for the specified task run ID.

aio_subscribe_to_stream

Subscribe to the stream chunks sent by a run via ctx.put_stream.

:yield: Each stream chunk as it arrives. :ytype: str

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the workflow run to subscribe to.required

Last updated on November 13, 2026

On this page