Runs ClientPython SDK
Bases: BaseRestClient
The runs client is a client for interacting with task and workflow runs within Hatchet.
Methods:
| Name | Description |
|---|---|
get | Get workflow run details for a given workflow run ID. |
aio_get | Get workflow run details for a given workflow run ID. |
get_status | Get workflow run status for a given workflow run ID. |
aio_get_status | Get workflow run status for a given workflow run ID. |
list | List task runs according to a set of filters, newest first. |
aio_list | List task runs according to a set of filters, newest first. |
create | Trigger a new workflow run. |
aio_create | Trigger a new workflow run. |
replay | Replay a task or workflow run. |
aio_replay | Replay a task or workflow run. |
bulk_replay | Replay task or workflow runs in bulk, according to a set of filters. |
aio_bulk_replay | Replay task or workflow runs in bulk, according to a set of filters. |
cancel | Cancel a task or workflow run. |
aio_cancel | Cancel a task or workflow run. |
bulk_cancel | Cancel task or workflow runs in bulk, according to a set of filters. |
aio_bulk_cancel | Cancel task or workflow runs in bulk, according to a set of filters. |
get_result | Get the result of a workflow run by its external ID. |
aio_get_result | Get the result of a workflow run by its external ID. |
get_run_ref | Get a reference to a workflow run. |
get_task_run | Get task run details for a given task run ID. |
aio_get_task_run | Get task run details for a given task run ID. |
aio_subscribe_to_stream | Subscribe 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:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_run_id | str | The ID of the workflow run to retrieve details for. | required |
Returns:
| Type | Description |
|---|---|
V1WorkflowRunDetails | Workflow run details for the specified workflow run ID. |
aio_get
Get workflow run details for a given workflow run ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_run_id | str | The ID of the workflow run to retrieve details for. | required |
Returns:
| Type | Description |
|---|---|
V1WorkflowRunDetails | Workflow run details for the specified workflow run ID. |
get_status
Get workflow run status for a given workflow run ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_run_id | str | The ID of the workflow run to retrieve details for. | required |
Returns:
| Type | Description |
|---|---|
Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED'] | The task status |
aio_get_status
Get workflow run status for a given workflow run ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_run_id | str | The ID of the workflow run to retrieve details for. | required |
Returns:
| Type | Description |
|---|---|
Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED'] | The task status |
list
List task runs according to a set of filters, newest first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
since | datetime | None | The start time for filtering task runs. | None |
only_tasks | bool | Whether to only list task runs. | False |
offset | int | None | The number of task runs to skip, counted across the whole time range. | None |
limit | int | None | The maximum number of task runs to return, counted across the whole time range. Returns every matching task run if not set. | None |
statuses | list[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']] | None | The statuses to filter task runs by. | None |
until | datetime | None | The end time for filtering task runs. | None |
additional_metadata | dict[str, str] | None | Additional metadata to filter task runs by. | None |
workflow_ids | list[str] | None | The workflow IDs to filter task runs by. | None |
worker_id | str | None | The worker ID to filter task runs by. | None |
parent_task_run_id | str | None | The ID of the parent task run to filter task runs by. | None |
triggering_event_id | str | None | The ID of the event that triggered the task run. | None |
include_payloads | bool | Whether to include payloads in the response. | True |
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
since | datetime | None | The start time for filtering task runs. | None |
only_tasks | bool | Whether to only list task runs. | False |
offset | int | None | The number of task runs to skip, counted across the whole time range. | None |
limit | int | None | The maximum number of task runs to return, counted across the whole time range. Returns every matching task run if not set. | None |
statuses | list[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']] | None | The statuses to filter task runs by. | None |
until | datetime | None | The end time for filtering task runs. | None |
additional_metadata | dict[str, str] | None | Additional metadata to filter task runs by. | None |
workflow_ids | list[str] | None | The workflow IDs to filter task runs by. | None |
worker_id | str | None | The worker ID to filter task runs by. | None |
parent_task_run_id | str | None | The ID of the parent task run to filter task runs by. | None |
triggering_event_id | str | None | The ID of the event that triggered the task run. | None |
include_payloads | bool | Whether to include payloads in the response. | True |
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_name | str | The name of the workflow to trigger. | required |
input | JSONSerializableMapping | The input data for the workflow run. | required |
additional_metadata | JSONSerializableMapping | None | Additional metadata associated with the workflow run. | None |
priority | Literal['LOW', 'MEDIUM', 'HIGH'] | None | The priority of the workflow run. | None |
Returns:
| Type | Description |
|---|---|
V1WorkflowRunDetails | The 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:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_name | str | The name of the workflow to trigger. | required |
input | JSONSerializableMapping | The input data for the workflow run. | required |
additional_metadata | JSONSerializableMapping | None | Additional metadata associated with the workflow run. | None |
priority | Literal['LOW', 'MEDIUM', 'HIGH'] | None | The priority of the workflow run. | None |
Returns:
| Type | Description |
|---|---|
V1WorkflowRunDetails | The details of the triggered workflow run. |
replay
Replay a task or workflow run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id | str | The external ID of the task or workflow run to replay. | required |
Returns:
| Type | Description |
|---|---|
None | None |
aio_replay
Replay a task or workflow run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id | str | The external ID of the task or workflow run to replay. | required |
Returns:
| Type | Description |
|---|---|
None | None |
bulk_replay
Replay task or workflow runs in bulk, according to a set of filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options | BulkCancelReplayOptions | Options for bulk replay, including filters and IDs. | required |
Returns:
| Type | Description |
|---|---|
None | None |
aio_bulk_replay
Replay task or workflow runs in bulk, according to a set of filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options | BulkCancelReplayOptions | Options for bulk replay, including filters and IDs. | required |
Returns:
| Type | Description |
|---|---|
None | None |
cancel
Cancel a task or workflow run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id | str | The external ID of the task or workflow run to cancel. | required |
Returns:
| Type | Description |
|---|---|
None | None |
aio_cancel
Cancel a task or workflow run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id | str | The external ID of the task or workflow run to cancel. | required |
Returns:
| Type | Description |
|---|---|
None | None |
bulk_cancel
Cancel task or workflow runs in bulk, according to a set of filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options | BulkCancelReplayOptions | Options for bulk cancel, including filters and IDs. | required |
Returns:
| Type | Description |
|---|---|
None | None |
aio_bulk_cancel
Cancel task or workflow runs in bulk, according to a set of filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options | BulkCancelReplayOptions | Options for bulk cancel, including filters and IDs. | required |
Returns:
| Type | Description |
|---|---|
None | None |
get_result
Get the result of a workflow run by its external ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_run_id | str | The external ID of the workflow run to retrieve the result for. | required |
Returns:
| Type | Description |
|---|---|
JSONSerializableMapping | The result of the workflow run. |
aio_get_result
Get the result of a workflow run by its external ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_run_id | str | The external ID of the workflow run to retrieve the result for. | required |
Returns:
| Type | Description |
|---|---|
JSONSerializableMapping | The result of the workflow run. |
get_run_ref
Get a reference to a workflow run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_run_id | str | The ID of the workflow run to get a reference to. | required |
Returns:
| Type | Description |
|---|---|
WorkflowRunRef | A reference to the specified workflow run. |
get_task_run
Get task run details for a given task run ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
task_run_id | str | The ID of the task run to retrieve details for. | required |
Returns:
| Type | Description |
|---|---|
TaskRunSummary | Task run details for the specified task run ID. |
aio_get_task_run
Get task run details for a given task run ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
task_run_id | str | The ID of the task run to retrieve details for. | required |
Returns:
| Type | Description |
|---|---|
TaskRunSummary | Task 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:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_run_id | str | The ID of the workflow run to subscribe to. | required |
Last updated on November 13, 2026