Python SDK

RunnablesPython SDK

Runnables in the Hatchet SDK are things that can be run, namely tasks and workflows. The two main types of runnables you'll encounter are:

  • Workflow, which lets you define tasks and call all of the run, schedule, etc. methods
  • Standalone, which is a single task that's returned by hatchet.task and can be run, scheduled, etc.

Workflow

Bases: BaseWorkflow[TWorkflowInput]

A Hatchet workflow, which allows you to define tasks to be run and perform actions on the workflow.

Workflows in Hatchet represent coordinated units of work that can be triggered, scheduled, or run on a cron schedule. Each workflow can contain multiple tasks that can be arranged in dependencies (DAGs), have customized retry behavior, timeouts, concurrency controls, and more.

Example:

from pydantic import BaseModel
from hatchet_sdk import Hatchet

class MyInput(BaseModel):
    name: str

hatchet = Hatchet()
workflow = hatchet.workflow(name="my-workflow", input_validator=MyInput)

@workflow.task()
def greet(input, ctx):
    return f"Hello, {input.name}!"

# Run the workflow
result = workflow.run(MyInput(name="World"))

Workflows support various execution patterns including:

  • One-time execution with run() or aio_run()
  • Scheduled execution with schedule()
  • Cron-based recurring execution with create_cron()
  • Bulk operations with run_many()

Tasks within workflows can be defined with @workflow.task() or @workflow.durable_task() decorators and can be arranged into complex dependency patterns.

Methods:

NameDescription
taskA decorator to transform a function into a Hatchet task that runs as part of a workflow.
batch_task.. note::
durable_taskA decorator to transform a function into a durable Hatchet task that runs as part of a workflow.
on_failure_taskA decorator to transform a function into a Hatchet on-failure task that runs as the last task in a workflow that had at least one task fail.
on_success_taskA decorator to transform a function into a Hatchet on-success task that runs as the last task in a workflow that had all upstream tasks succeed.
runRun the workflow synchronously and wait for it to complete.
aio_runRun the workflow asynchronously and wait for it to complete.
run_manyRun a workflow in bulk.
aio_run_manyRun a workflow in bulk asynchronously.
scheduleSchedule a workflow to run at a specific time.
aio_scheduleSchedule a workflow to run at a specific time.
create_cronCreate a cron job for the workflow.
aio_create_cronCreate a cron job for the workflow.
create_bulk_run_itemCreate a bulk run item for the workflow. This is intended to be used in conjunction with the various run_many methods.
list_runsList runs of the workflow.
aio_list_runsList runs of the workflow.
create_filterCreate a new filter.
aio_create_filterCreate a new filter.

Attributes

name

The (namespaced) name of the workflow.

tasks

Functions

task

A decorator to transform a function into a Hatchet task that runs as part of a workflow.

Parameters:

NameTypeDescriptionDefault
namestr | NoneThe name of the task. If not specified, defaults to the name of the function being wrapped by the task decorator.None
schedule_timeouttimedelta | NoneThe maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time.None
execution_timeouttimedelta | NoneThe maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time.None
parentslist[Task[TWorkflowInput, Any]] | NoneA list of tasks that are parents of the task. Note: Parents must be defined before their children.None
retriesint | NoneThe number of times to retry the task before failing.None
rate_limitslist[RateLimit] | NoneA list of rate limit configurations for the task.None
desired_worker_labelslist[DesiredWorkerLabel] | NoneA list of desired worker labels that determine to which worker the task should be assigned. See documentation and examples on affinity and worker labels for more details.None
backoff_factorfloat | NoneThe backoff factor for controlling exponential backoff in retries.None
backoff_maxtimedelta | NoneThe maximum delay between retries when using exponential backoff.None
concurrencyint | ConcurrencyStrategy | Sequence[ConcurrencyStrategy] | NoneA list of concurrency expressions for the task. If an integer is provided, it is treated as a constant concurrency limit with a GROUP_ROUND_ROBIN strategy, which means that only N runs of the task may execute at any given time.None
wait_forlist[Condition | OrGroup] | NoneA list of conditions that must be met before the task can run.None
skip_iflist[Condition | OrGroup] | NoneA list of conditions that, if met, will cause the task to be skipped.None
cancel_iflist[Condition | OrGroup] | NoneA list of conditions that, if met, will cause the task to be canceled.None
slot_costint | NoneThe number of default worker slots this task consumes. A normal task consumes one. Set it higher for a task that needs more memory or CPU, so a worker runs fewer of them at once. A single worker must have that many free slots to run it.None

Returns:

TypeDescription
Callable[[Callable[Concatenate[TWorkflowInput, Context, P], R | CoroutineLike[R]]], Task[TWorkflowInput, R]]A decorator which creates a Task object.

Raises:

TypeDescription
ValueErrorIf slot_cost is not positive.

batch_task

.. note:: Preview: This function is in beta and may change in future releases.

A decorator to transform a function into a Hatchet batch task that runs as part of a workflow.

Batch tasks buffer individual executions until Hatchet flushes the batch (size reached or flush interval), then invoke the handler once with all buffered inputs keyed by task run ID.

The handler must return a dict mapping each task run ID to its output, or use broadcast_output to return the same result to all callsites.

durable_task

A decorator to transform a function into a durable Hatchet task that runs as part of a workflow.

IMPORTANT: This decorator creates a durable task, which works using Hatchet's durable execution capabilities. This is an advanced feature of Hatchet.

See the Hatchet docs for more information on durable execution to decide if this is right for you.

Parameters:

NameTypeDescriptionDefault
namestr | NoneThe name of the task. If not specified, defaults to the name of the function being wrapped by the task decorator.None
schedule_timeouttimedelta | NoneThe maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time.None
execution_timeouttimedelta | NoneThe maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time.None
parentslist[Task[TWorkflowInput, Any]] | NoneA list of tasks that are parents of the task. Note: Parents must be defined before their children.None
retriesint | NoneThe number of times to retry the task before failing.None
rate_limitslist[RateLimit] | NoneA list of rate limit configurations for the task.None
desired_worker_labelslist[DesiredWorkerLabel] | NoneA list of desired worker labels that determine to which worker the task should be assigned. See documentation and examples on affinity and worker labels for more details.None
backoff_factorfloat | NoneThe backoff factor for controlling exponential backoff in retries.None
backoff_maxtimedelta | NoneThe maximum delay between retries when using exponential backoff.None
concurrencyint | ConcurrencyStrategy | Sequence[ConcurrencyStrategy] | NoneA list of concurrency expressions for the task. If an integer is provided, it is treated as a constant concurrency limit with a GROUP_ROUND_ROBIN strategy, which means that only N runs of the task may execute at any given time.None
wait_forlist[Condition | OrGroup] | NoneA list of conditions that must be met before the task can run.None
skip_iflist[Condition | OrGroup] | NoneA list of conditions that, if met, will cause the task to be skipped.None
cancel_iflist[Condition | OrGroup] | NoneA list of conditions that, if met, will cause the task to be canceled.None
eviction_policyEvictionPolicy | NoneAn optional eviction policy controlling when this durable task can be evicted from a worker slot while waiting.DEFAULT_DURABLE_TASK_EVICTION_POLICY
slot_costint | NoneThe number of durable worker slots this task consumes. A normal durable task consumes one. Set it higher for a task that needs more memory or CPU, so a worker runs fewer of them at once. A single worker must have that many free durable slots to run it.None

Returns:

TypeDescription
Callable[[Callable[Concatenate[TWorkflowInput, DurableContext, P], R | CoroutineLike[R]]], Task[TWorkflowInput, R]]A decorator which creates a Task object.

Raises:

TypeDescription
ValueErrorIf slot_cost is not positive.

on_failure_task

A decorator to transform a function into a Hatchet on-failure task that runs as the last task in a workflow that had at least one task fail.

Parameters:

NameTypeDescriptionDefault
namestr | NoneThe name of the on-failure task. If not specified, defaults to the name of the function being wrapped by the on_failure_task decorator.None
schedule_timeouttimedelta | NoneThe maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time. Falls back to the workflow's task_defaults.None
execution_timeouttimedelta | NoneThe maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time. Falls back to the workflow's task_defaults.None
retriesint | NoneThe number of times to retry the on-failure task before failing. Falls back to the workflow's task_defaults.None
rate_limitslist[RateLimit] | NoneA list of rate limit configurations for the on-failure task.None
backoff_factorfloat | NoneThe backoff factor for controlling exponential backoff in retries.None
backoff_maxtimedelta | NoneThe maximum delay between retries when using exponential backoff.None
concurrencyint | ConcurrencyStrategy | Sequence[ConcurrencyStrategy] | NoneA list of concurrency expressions for the on-failure task. If an integer is provided, it is treated as a constant concurrency limit with a GROUP_ROUND_ROBIN strategy, which means that only N runs of the task may execute at any given time.None

Returns:

TypeDescription
Callable[[Callable[Concatenate[TWorkflowInput, Context, P], R | CoroutineLike[R]]], Task[TWorkflowInput, R]]A decorator which creates a Task object.

on_success_task

A decorator to transform a function into a Hatchet on-success task that runs as the last task in a workflow that had all upstream tasks succeed.

Parameters:

NameTypeDescriptionDefault
namestr | NoneThe name of the on-success task. If not specified, defaults to the name of the function being wrapped by the on_success_task decorator.None
schedule_timeouttimedelta | NoneThe maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time. Falls back to the workflow's task_defaults.None
execution_timeouttimedelta | NoneThe maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time. Falls back to the workflow's task_defaults.None
retriesint | NoneThe number of times to retry the on-success task before failing. Falls back to the workflow's task_defaults.None
rate_limitslist[RateLimit] | NoneA list of rate limit configurations for the on-success task.None
backoff_factorfloat | NoneThe backoff factor for controlling exponential backoff in retries.None
backoff_maxtimedelta | NoneThe maximum delay between retries when using exponential backoff.None
concurrencyint | ConcurrencyStrategy | Sequence[ConcurrencyStrategy] | NoneA list of concurrency expressions for the on-success task. If an integer is provided, it is treated as a constant concurrency limit with a GROUP_ROUND_ROBIN strategy, which means that only N runs of the task may execute at any given time.None

Returns:

TypeDescription
Callable[[Callable[Concatenate[TWorkflowInput, Context, P], R | CoroutineLike[R]]], Task[TWorkflowInput, R]]A decorator which creates a Task object.

run

Run the workflow synchronously and wait for it to complete.

This method triggers a workflow run, blocks until completion, and returns the final result.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInputThe input data for the workflow, must match the workflow's input type.cast('TWorkflowInput', None)
wait_for_resultboolIf True, block until completion and return the result. If False, return a WorkflowRunRef immediately.True
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the workflow run.None
stickyboolWhether to run the workflow on the same worker as the task that triggers it.False
desired_worker_labelslist[DesiredWorkerLabel] | NoneA list of desired worker labels for worker affinity.None

Returns:

TypeDescription
WorkflowRunRef | dict[str, Any]The result of the workflow execution as a dictionary, or a WorkflowRunRef if wait_for_result is False.

aio_run

Run the workflow asynchronously and wait for it to complete.

This method triggers a workflow run, awaits until completion, and returns the final result.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInputThe input data for the workflow, must match the workflow's input type.cast('TWorkflowInput', None)
wait_for_resultboolIf True, await completion and return the result. If False, return a WorkflowRunRef immediately.True
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the workflow run.None
stickyboolWhether to run the workflow on the same worker as the task that triggers it.False
desired_worker_labelslist[DesiredWorkerLabel] | NoneA list of desired worker labels for worker affinity.None

Returns:

TypeDescription
WorkflowRunRef | dict[str, Any]The result of the workflow execution as a dictionary, or a WorkflowRunRef if wait_for_result is False.

Raises:

TypeDescription
RuntimeErrorIf the workflow is triggered within a durable context that supports durable eviction but fails to spawn a durable child workflow.

run_many

Run a workflow in bulk.

Parameters:

NameTypeDescriptionDefault
workflowslist[WorkflowRunTriggerConfig]A list of WorkflowRunTriggerConfig objects, each representing a workflow run to be triggered.required
return_exceptionsboolIf True, exceptions will be returned as part of the results instead of raising them.False
wait_for_resultboolIf True, block until all runs complete and return results. If False, return a list of WorkflowRunRef immediately.True

Returns:

TypeDescription
list[dict[str, Any]] | list[dict[str, Any] | BaseException] | list[WorkflowRunRef]A list of results for each workflow run, or a list of WorkflowRunRef if wait_for_result is False.

aio_run_many

Run a workflow in bulk asynchronously.

Parameters:

NameTypeDescriptionDefault
workflowslist[WorkflowRunTriggerConfig]A list of WorkflowRunTriggerConfig objects, each representing a workflow run to be triggered.required
return_exceptionsboolIf True, exceptions will be returned as part of the results instead of raising them.False
wait_for_resultboolIf True, await completion and return results. If False, return a list of WorkflowRunRef immediately.True

Returns:

TypeDescription
list[dict[str, Any]] | list[dict[str, Any] | BaseException] | list[WorkflowRunRef]A list of results for each workflow run, or a list of WorkflowRunRef if wait_for_result is False.

schedule

Schedule a workflow to run at a specific time.

Parameters:

NameTypeDescriptionDefault
trigger_atdatetimeThe time at which to schedule the workflow.required
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the scheduled workflow run.None

Returns:

TypeDescription
ScheduledRunThe scheduled run.

aio_schedule

Schedule a workflow to run at a specific time.

Parameters:

NameTypeDescriptionDefault
trigger_atdatetimeThe time at which to schedule the workflow.required
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the scheduled workflow run.None

Returns:

TypeDescription
ScheduledRunThe scheduled run.

create_cron

Create a cron job for the workflow.

Parameters:

NameTypeDescriptionDefault
cron_namestrThe name of the cron job.required
expressionstrThe cron expression that defines the schedule for the cron job.required
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
additional_metadataJSONSerializableMapping | NoneAdditional metadata for the cron job.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the cron job.None

Returns:

TypeDescription
CronTriggerThe created cron trigger.

aio_create_cron

Create a cron job for the workflow.

Parameters:

NameTypeDescriptionDefault
cron_namestrThe name of the cron job.required
expressionstrThe cron expression that defines the schedule for the cron job.required
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
additional_metadataJSONSerializableMapping | NoneAdditional metadata for the cron job.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the cron job.None

Returns:

TypeDescription
CronTriggerThe created cron trigger.

create_bulk_run_item

Create a bulk run item for the workflow. This is intended to be used in conjunction with the various run_many methods.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the workflow run.None
stickyboolWhether to run the workflow on the same worker as the task that triggers it.False
desired_worker_labelslist[DesiredWorkerLabel] | NoneA list of desired worker labels for worker affinity.None

Returns:

TypeDescription
WorkflowRunTriggerConfigA WorkflowRunTriggerConfig object that can be used to trigger the workflow run, which you then pass into the run_many methods.

list_runs

List runs of the workflow.

Parameters:

NameTypeDescriptionDefault
sincedatetime | NoneThe start time for the runs to be listed.None
untildatetime | NoneThe end time for the runs to be listed.None
limitint | NoneThe maximum number of runs to be listed. Returns every matching run if not set.None
offsetint | NoneThe offset for pagination.None
statuseslist[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']] | NoneThe statuses of the runs to be listed.None
additional_metadatadict[str, str] | NoneAdditional metadata for filtering the runs.None
worker_idstr | NoneThe ID of the worker that ran the tasks.None
parent_task_run_idstr | NoneThe ID of the parent task run.None
only_tasksboolWhether to list only task runs.False
triggering_event_idstr | NoneThe ID of the event that triggered the task run.None

Returns:

TypeDescription
list[TaskRunSummary]The runs of the workflow, as TaskRunSummary objects.

aio_list_runs

List runs of the workflow.

Parameters:

NameTypeDescriptionDefault
sincedatetime | NoneThe start time for the runs to be listed.None
untildatetime | NoneThe end time for the runs to be listed.None
limitint | NoneThe maximum number of runs to be listed. Returns every matching run if not set.None
offsetint | NoneThe offset for pagination.None
statuseslist[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']] | NoneThe statuses of the runs to be listed.None
additional_metadatadict[str, str] | NoneAdditional metadata for filtering the runs.None
worker_idstr | NoneThe ID of the worker that ran the tasks.None
parent_task_run_idstr | NoneThe ID of the parent task run.None
only_tasksboolWhether to list only task runs.False
triggering_event_idstr | NoneThe ID of the event that triggered the task run.None

Returns:

TypeDescription
list[TaskRunSummary]The runs of the workflow, as TaskRunSummary objects.

create_filter

Create a new filter.

Parameters:

NameTypeDescriptionDefault
expressionstrThe expression to evaluate for the filter.required
scopestrThe scope for the filter.required
payloadJSONSerializableMapping | NoneThe payload to send with the filter.None

Returns:

TypeDescription
V1FilterThe created filter.

aio_create_filter

Create a new filter.

Parameters:

NameTypeDescriptionDefault
expressionstrThe expression to evaluate for the filter.required
scopestrThe scope for the filter.required
payloadJSONSerializableMapping | NoneThe payload to send with the filter.None

Returns:

TypeDescription
V1FilterThe created filter.

Task

Bases: Generic[TWorkflowInput, R]

Methods:

NameDescription
mock_runMimic the execution of a task. This method is intended to be used to unit test
aio_mock_runMimic the execution of a task. This method is intended to be used to unit test

Functions

mock_run

Mimic the execution of a task. This method is intended to be used to unit test tasks without needing to interact with the Hatchet engine. Use mock_run for sync tasks and aio_mock_run for async tasks.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInput | NoneThe input to the task.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the task.None
parent_outputsdict[str, JSONSerializableMapping] | NoneOutputs from parent tasks, if any. This is useful for mimicking DAG functionality. For instance, if you have a task task_2 that has a parent which is task_1, you can pass parent_outputs={"task_1": {"result": "Hello, world!"}} to task_2.mock_run() to be able to access ctx.task_output(task_1) in task_2.None
retry_countintThe number of times the task has been retried.0
lifespanAnyThe lifespan to be used in the task, which is useful if one was set on the worker. This will allow you to access ctx.lifespan inside of your task.None
dependenciesdict[str, Any] | NoneDependencies to be injected into the task. This is useful for tasks that have dependencies defined using Depends. IMPORTANT: You must pass the dependencies directly, not the Depends objects themselves. For example, if you have a task that has a dependency config: Annotated[str, Depends(get_config)], you should pass dependencies={"config": "config_value"} to aio_mock_run.None
task_run_errorsdict[str, TaskRunError] | NoneErrors from upstream tasks, keyed by task name. This is useful for testing on-failure tasks that read ctx.task_run_errors or ctx.get_task_run_error.None
filter_payloadJSONSerializableMapping | NoneThe payload of the filter that matched the triggering event, which will be available as ctx.filter_payload.None
workflow_run_idstr | NoneThe id of the workflow run, which will be available as ctx.workflow_run_id. A random id is used if not provided.None
task_run_idstr | NoneThe id of the task run, which will be available as ctx.task_run_id. A random id is used if not provided.None

Returns:

TypeDescription
RThe output of the task.

Raises:

TypeDescription
TypeErrorIf the task is an async function and mock_run is called, or if the task is a sync function and aio_mock_run is called.

aio_mock_run

Mimic the execution of a task. This method is intended to be used to unit test tasks without needing to interact with the Hatchet engine. Use mock_run for sync tasks and aio_mock_run for async tasks.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInput | NoneThe input to the task.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the task.None
parent_outputsdict[str, JSONSerializableMapping] | NoneOutputs from parent tasks, if any. This is useful for mimicking DAG functionality. For instance, if you have a task task_2 that has a parent which is task_1, you can pass parent_outputs={"task_1": {"result": "Hello, world!"}} to task_2.mock_run() to be able to access ctx.task_output(task_1) in task_2.None
retry_countintThe number of times the task has been retried.0
lifespanAnyThe lifespan to be used in the task, which is useful if one was set on the worker. This will allow you to access ctx.lifespan inside of your task.None
dependenciesdict[str, Any] | NoneDependencies to be injected into the task. This is useful for tasks that have dependencies defined using Depends. IMPORTANT: You must pass the dependencies directly, not the Depends objects themselves. For example, if you have a task that has a dependency config: Annotated[str, Depends(get_config)], you should pass dependencies={"config": "config_value"} to aio_mock_run.None
task_run_errorsdict[str, TaskRunError] | NoneErrors from upstream tasks, keyed by task name. This is useful for testing on-failure tasks that read ctx.task_run_errors or ctx.get_task_run_error.None
filter_payloadJSONSerializableMapping | NoneThe payload of the filter that matched the triggering event, which will be available as ctx.filter_payload.None
workflow_run_idstr | NoneThe id of the workflow run, which will be available as ctx.workflow_run_id. A random id is used if not provided.None
task_run_idstr | NoneThe id of the task run, which will be available as ctx.task_run_id. A random id is used if not provided.None

Returns:

TypeDescription
RThe output of the task.

Raises:

TypeDescription
TypeErrorIf the task is an async function and mock_run is called, or if the task is a sync function and aio_mock_run is called.

Standalone

Bases: BaseWorkflow[TWorkflowInput], Generic[TWorkflowInput, R]

Methods:

NameDescription
runRun the workflow synchronously and wait for it to complete.
aio_runRun the workflow asynchronously and wait for it to complete.
run_manyRun a workflow in bulk.
aio_run_manyRun a workflow in bulk asynchronously.
scheduleSchedule a workflow to run at a specific time.
aio_scheduleSchedule a workflow to run at a specific time.
create_cronCreate a cron job for the workflow.
aio_create_cronCreate a cron job for the workflow.
create_bulk_run_itemCreate a bulk run item for the workflow. This is intended to be used in conjunction with the various run_many methods.
list_runsList runs of the workflow.
aio_list_runsList runs of the workflow.
create_filterCreate a new filter.
aio_create_filterCreate a new filter.
deletePermanently delete the workflow.
aio_deletePermanently delete the workflow.
get_run_refGet a reference to a task run by its run ID.
get_resultGet the result of a task run by its run ID.
aio_get_resultGet the result of a task run by its run ID.
mock_runMimic the execution of a task. This method is intended to be used to unit test
aio_mock_runMimic the execution of a task. This method is intended to be used to unit test

Functions

run

Run the workflow synchronously and wait for it to complete.

This method triggers a workflow run, blocks until completion, and returns the extracted result.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
wait_for_resultboolIf True, block until completion and return the result. If False, return a TaskRunRef immediately.True
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the workflow run.None
stickyboolWhether to run the workflow on the same worker as the task that triggers it.False
desired_worker_labelslist[DesiredWorkerLabel] | NoneA list of desired worker labels for worker affinity.None

Returns:

TypeDescription
TaskRunRef[TWorkflowInput, R] | RThe extracted result of the workflow execution, or a TaskRunRef if wait_for_result is False.

aio_run

Run the workflow asynchronously and wait for it to complete.

This method triggers a workflow run, awaits until completion, and returns the extracted result.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInputThe input data for the workflow, must match the workflow's input type.cast('TWorkflowInput', None)
wait_for_resultboolIf True, await completion and return the result. If False, return a TaskRunRef immediately.True
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the workflow run.None
stickyboolWhether to run the workflow on the same worker as the task that triggers it.False
desired_worker_labelslist[DesiredWorkerLabel] | NoneA list of desired worker labels for worker affinity.None

Returns:

TypeDescription
TaskRunRef[TWorkflowInput, R] | RThe extracted result of the workflow execution, or a TaskRunRef if wait_for_result is False.

run_many

Run a workflow in bulk.

Parameters:

NameTypeDescriptionDefault
workflowslist[WorkflowRunTriggerConfig]A list of WorkflowRunTriggerConfig objects, each representing a workflow run to be triggered.required
return_exceptionsboolIf True, exceptions will be returned as part of the results instead of raising them.False
wait_for_resultboolIf True, block until all runs complete and return results. If False, return a list of TaskRunRef immediately.True

Returns:

TypeDescription
list[R] | list[R | BaseException] | list[TaskRunRef[TWorkflowInput, R]]A list of results for each workflow run, or a list of TaskRunRef if wait_for_result is False.

aio_run_many

Run a workflow in bulk asynchronously.

Parameters:

NameTypeDescriptionDefault
workflowslist[WorkflowRunTriggerConfig]A list of WorkflowRunTriggerConfig objects, each representing a workflow run to be triggered.required
return_exceptionsboolIf True, exceptions will be returned as part of the results instead of raising them.False
wait_for_resultboolIf True, await completion and return results. If False, return a list of TaskRunRef immediately.True

Returns:

TypeDescription
list[R] | list[R | BaseException] | list[TaskRunRef[TWorkflowInput, R]]A list of results for each workflow run, or a list of TaskRunRef if wait_for_result is False.

schedule

Schedule a workflow to run at a specific time.

Parameters:

NameTypeDescriptionDefault
trigger_atdatetimeThe time at which to schedule the workflow.required
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the scheduled workflow run.None

Returns:

TypeDescription
ScheduledRunThe scheduled run.

aio_schedule

Schedule a workflow to run at a specific time.

Parameters:

NameTypeDescriptionDefault
trigger_atdatetimeThe time at which to schedule the workflow.required
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the scheduled workflow run.None

Returns:

TypeDescription
ScheduledRunThe scheduled run.

create_cron

Create a cron job for the workflow.

Parameters:

NameTypeDescriptionDefault
cron_namestrThe name of the cron job.required
expressionstrThe cron expression that defines the schedule for the cron job.required
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
additional_metadataJSONSerializableMapping | NoneAdditional metadata for the cron job.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the cron job.None

Returns:

TypeDescription
CronTriggerThe created cron trigger.

aio_create_cron

Create a cron job for the workflow.

Parameters:

NameTypeDescriptionDefault
cron_namestrThe name of the cron job.required
expressionstrThe cron expression that defines the schedule for the cron job.required
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
additional_metadataJSONSerializableMapping | NoneAdditional metadata for the cron job.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the cron job.None

Returns:

TypeDescription
CronTriggerThe created cron trigger.

create_bulk_run_item

Create a bulk run item for the workflow. This is intended to be used in conjunction with the various run_many methods.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInputThe input data for the workflow.cast('TWorkflowInput', None)
child_keystr | NoneAn optional key for deduplicating child workflow runs.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the workflow run.None
priorityLiteral['LOW', 'MEDIUM', 'HIGH'] | NoneThe priority of the workflow run.None
stickyboolWhether to run the workflow on the same worker as the task that triggers it.False
desired_worker_labelslist[DesiredWorkerLabel] | NoneA list of desired worker labels for worker affinity.None

Returns:

TypeDescription
WorkflowRunTriggerConfigA WorkflowRunTriggerConfig object that can be used to trigger the workflow run, which you then pass into the run_many methods.

list_runs

List runs of the workflow.

Parameters:

NameTypeDescriptionDefault
sincedatetime | NoneThe start time for the runs to be listed.None
untildatetime | NoneThe end time for the runs to be listed.None
limitint | NoneThe maximum number of runs to be listed. Returns every matching run if not set.None
offsetint | NoneThe offset for pagination.None
statuseslist[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']] | NoneThe statuses of the runs to be listed.None
additional_metadatadict[str, str] | NoneAdditional metadata for filtering the runs.None
worker_idstr | NoneThe ID of the worker that ran the tasks.None
parent_task_run_idstr | NoneThe ID of the parent task run.None
only_tasksboolWhether to list only task runs.False
triggering_event_idstr | NoneThe ID of the event that triggered the task run.None

Returns:

TypeDescription
list[TaskRunSummary]The runs of the workflow, as TaskRunSummary objects.

aio_list_runs

List runs of the workflow.

Parameters:

NameTypeDescriptionDefault
sincedatetime | NoneThe start time for the runs to be listed.None
untildatetime | NoneThe end time for the runs to be listed.None
limitint | NoneThe maximum number of runs to be listed. Returns every matching run if not set.None
offsetint | NoneThe offset for pagination.None
statuseslist[Literal['QUEUED', 'RUNNING', 'COMPLETED', 'CANCELLED', 'FAILED']] | NoneThe statuses of the runs to be listed.None
additional_metadatadict[str, str] | NoneAdditional metadata for filtering the runs.None
worker_idstr | NoneThe ID of the worker that ran the tasks.None
parent_task_run_idstr | NoneThe ID of the parent task run.None
only_tasksboolWhether to list only task runs.False
triggering_event_idstr | NoneThe ID of the event that triggered the task run.None

Returns:

TypeDescription
list[TaskRunSummary]The runs of the workflow, as TaskRunSummary objects.

create_filter

Create a new filter.

Parameters:

NameTypeDescriptionDefault
expressionstrThe expression to evaluate for the filter.required
scopestrThe scope for the filter.required
payloadJSONSerializableMapping | NoneThe payload to send with the filter.None

Returns:

TypeDescription
V1FilterThe created filter.

aio_create_filter

Create a new filter.

Parameters:

NameTypeDescriptionDefault
expressionstrThe expression to evaluate for the filter.required
scopestrThe scope for the filter.required
payloadJSONSerializableMapping | NoneThe payload to send with the filter.None

Returns:

TypeDescription
V1FilterThe created filter.

delete

Permanently delete the workflow.

DANGEROUS: This will delete a workflow and all of its data

aio_delete

Permanently delete the workflow.

DANGEROUS: This will delete a workflow and all of its data

get_run_ref

Get a reference to a task run by its run ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the run to get the reference for.required

Returns:

TypeDescription
TaskRunRef[TWorkflowInput, R]A TaskRunRef object representing the reference to the task run.

get_result

Get the result of a task run by its run ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the run to get the result for.required

Returns:

TypeDescription
RThe result of the task run.

aio_get_result

Get the result of a task run by its run ID.

Parameters:

NameTypeDescriptionDefault
workflow_run_idstrThe ID of the run to get the result for.required

Returns:

TypeDescription
RThe result of the task run.

mock_run

Mimic the execution of a task. This method is intended to be used to unit test tasks without needing to interact with the Hatchet engine. Use mock_run for sync tasks and aio_mock_run for async tasks.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInput | NoneThe input to the task.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the task.None
parent_outputsdict[str, JSONSerializableMapping] | NoneOutputs from parent tasks, if any. This is useful for mimicking DAG functionality. For instance, if you have a task task_2 that has a parent which is task_1, you can pass parent_outputs={"task_1": {"result": "Hello, world!"}} to task_2.mock_run() to be able to access ctx.task_output(task_1) in task_2.None
retry_countintThe number of times the task has been retried.0
lifespanAnyThe lifespan to be used in the task, which is useful if one was set on the worker. This will allow you to access ctx.lifespan inside of your task.None
dependenciesdict[str, Any] | NoneDependencies to be injected into the task. This is useful for tasks that have dependencies defined using Depends. IMPORTANT: You must pass the dependencies directly, not the Depends objects themselves. For example, if you have a task that has a dependency config: Annotated[str, Depends(get_config)], you should pass dependencies={"config": "config_value"} to aio_mock_run.None
task_run_errorsdict[str, TaskRunError] | NoneErrors from upstream tasks, keyed by task name. This is useful for testing on-failure tasks that read ctx.task_run_errors or ctx.get_task_run_error.None
filter_payloadJSONSerializableMapping | NoneThe payload of the filter that matched the triggering event, which will be available as ctx.filter_payload.None
workflow_run_idstr | NoneThe id of the workflow run, which will be available as ctx.workflow_run_id. A random id is used if not provided.None
task_run_idstr | NoneThe id of the task run, which will be available as ctx.task_run_id. A random id is used if not provided.None

Returns:

TypeDescription
RThe output of the task.

aio_mock_run

Mimic the execution of a task. This method is intended to be used to unit test tasks without needing to interact with the Hatchet engine. Use mock_run for sync tasks and aio_mock_run for async tasks.

Parameters:

NameTypeDescriptionDefault
inputTWorkflowInput | NoneThe input to the task.None
additional_metadataJSONSerializableMapping | NoneAdditional metadata to attach to the task.None
parent_outputsdict[str, JSONSerializableMapping] | NoneOutputs from parent tasks, if any. This is useful for mimicking DAG functionality. For instance, if you have a task task_2 that has a parent which is task_1, you can pass parent_outputs={"task_1": {"result": "Hello, world!"}} to task_2.mock_run() to be able to access ctx.task_output(task_1) in task_2.None
retry_countintThe number of times the task has been retried.0
lifespanAnyThe lifespan to be used in the task, which is useful if one was set on the worker. This will allow you to access ctx.lifespan inside of your task.None
dependenciesdict[str, Any] | NoneDependencies to be injected into the task. This is useful for tasks that have dependencies defined using Depends. IMPORTANT: You must pass the dependencies directly, not the Depends objects themselves. For example, if you have a task that has a dependency config: Annotated[str, Depends(get_config)], you should pass dependencies={"config": "config_value"} to aio_mock_run.None
task_run_errorsdict[str, TaskRunError] | NoneErrors from upstream tasks, keyed by task name. This is useful for testing on-failure tasks that read ctx.task_run_errors or ctx.get_task_run_error.None
filter_payloadJSONSerializableMapping | NoneThe payload of the filter that matched the triggering event, which will be available as ctx.filter_payload.None
workflow_run_idstr | NoneThe id of the workflow run, which will be available as ctx.workflow_run_id. A random id is used if not provided.None
task_run_idstr | NoneThe id of the task run, which will be available as ctx.task_run_id. A random id is used if not provided.None

Returns:

TypeDescription
RThe output of the task.

Last updated on November 13, 2026

On this page