Hatchet Python SDK Reference
This is the Python SDK reference, documenting methods available for interacting with Hatchet resources. Check out the user guide for an introduction for getting your first tasks running.
The Hatchet Python Client
Main client for interacting with the Hatchet SDK.
This class provides access to various client interfaces and utility methods for working with Hatchet workers, workflows, tasks, and our various feature clients.
Methods:
| Name | Description |
|---|---|
worker | Create a Hatchet worker on which to run workflows. |
workflow | Define a Hatchet workflow, which can then declare tasks and be run, scheduled, and so on. |
task | A decorator to transform a function into a standalone Hatchet task that runs as part of a workflow. |
durable_task | A decorator to transform a function into a standalone Hatchet durable task that runs as part of a workflow. |
from_embedded | Run a full Hatchet engine locally and return a client wired to it. |
stop_embedded | Gracefully stop the embedded engine started by Hatchet.from_embedded(). |
aio_stop_embedded | Async variant of stop_embedded. |
Attributes
cron
The cron client is a client for managing cron workflows within Hatchet.
event
The event client, which you can use to push events to Hatchet.
logs
The logs client is a client for interacting with Hatchet's logs API.
metrics
The metrics client is a client for reading metrics out of Hatchet's metrics API.
rate_limits
The rate limits client is a wrapper for Hatchet's gRPC API that makes it easier to work with rate limits in Hatchet.
runs
The runs client is a client for interacting with task and workflow runs within Hatchet.
scheduled
The scheduled client is a client for managing scheduled workflows within Hatchet.
workers
The workers client is a client for managing workers programmatically within Hatchet.
workflows
The workflows client is a client for managing workflows programmatically within Hatchet.
Note that workflows are the declaration, not the individual runs. If you're looking for runs, use the RunsClient instead.
tenant_id
The tenant id you're operating in.
namespace
The current namespace you're interacting with.
Functions
worker
Create a Hatchet worker on which to run workflows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name | str | The name of the worker. | required |
slots | int | None | slot count for standard tasks. | None |
durable_slots | int | None | slot count for durable tasks. | None |
labels | dict[str, str | int] | None | A dictionary of labels to assign to the worker. For more details, view examples on affinity and worker labels. | None |
workflows | list[BaseWorkflow[Any]] | None | A list of workflows to register on the worker, as a shorthand for calling register_workflow on each or register_workflows on all of them. | None |
lifespan | LifespanFn | None | A lifespan function to run on the worker. This function will be called when the worker is started, and can be used to perform any setup or teardown tasks. | None |
Returns:
| Type | Description |
|---|---|
Worker | The created Worker object, which exposes an instance method start which can be called to start the worker. |
Raises:
| Type | Description |
|---|---|
TypeError | If any of the items in workflows is not an instance of Workflow or Standalone, which are the two types of workflow objects that can be passed to a worker. This is to catch a common mistake where users pass the result of a task declaration method like Workflow.task instead of the workflow object itself. |
workflow
Define a Hatchet workflow, which can then declare tasks and be run, scheduled, and so on.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name | str | The name of the workflow. | required |
description | str | None | A description for the workflow | None |
input_validator | type[TWorkflowInput] | None | A Pydantic model to use as a validator for the input to the tasks in the workflow. If no validator is provided, defaults to an EmptyModel under the hood. The EmptyModel is a Pydantic model with no fields specified, and with the extra config option set to "allow". | None |
on_events | list[str] | None | A list of event triggers for the workflow - events which cause the workflow to be run. | None |
on_crons | list[str] | None | A list of cron triggers for the workflow. | None |
cron_input | TWorkflowInput | None | An optional input to provide to runs triggered by the workflow's on_crons schedules. Should be an instance of the workflow's input model. | None |
version | str | None | A version for the workflow | None |
sticky | StickyStrategy | None | A sticky strategy for the workflow | None |
default_priority | int | Priority | The priority of the workflow. Higher values will cause this workflow to have priority in scheduling over other, lower priority ones. | LOW |
concurrency | int | ConcurrencyExpression | list[ConcurrencyExpression] | None | A concurrency object controlling the concurrency settings for this workflow. 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 |
task_defaults | TaskDefaults | A TaskDefaults object controlling the default task settings for this workflow. | TaskDefaults() |
default_filters | list[DefaultFilter] | None | A list of filters to create with the workflow is created. Note that this is a helper to allow you to create filters "declaratively" without needing to make a separate API call once the workflow is created to create them. | None |
default_additional_metadata | JSONSerializableMapping | None | A dictionary of additional metadata to attach to each run of this workflow by default. | None |
idempotency | TTLBasedIdempotencyConfig | StatusBasedIdempotencyConfig | None | An optional idempotency configuration for the workflow, controlling how Hatchet should determine if two runs of this workflow are "the same" for the purposes of deduplication and idempotent execution. | None |
Returns:
| Type | Description |
|---|---|
Workflow[EmptyModel] | Workflow[TWorkflowInput] | The created Workflow object, which can be used to declare tasks, run the workflow, and so on. |
task
A decorator to transform a function into a standalone Hatchet task that runs as part of a workflow.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name | str | None | The name of the task. If not specified, defaults to the name of the function being wrapped by the task decorator. | None |
description | str | None | An optional description for the task. | None |
input_validator | type[TWorkflowInput] | None | A Pydantic model to use as a validator for the input to the task. If no validator is provided, defaults to an EmptyModel. | None |
on_events | list[str] | None | A list of event triggers for the task - events which cause the task to be run. | None |
on_crons | list[str] | None | A list of cron triggers for the task. | None |
cron_input | TWorkflowInput | None | An optional input to provide to runs triggered by the task's on_crons schedules. Should be an instance of the task's input model. | None |
version | str | None | A version for the task. | None |
sticky | StickyStrategy | None | A sticky strategy for the task. | None |
default_priority | int | Priority | The priority of the task. Higher values will cause this task to have priority in scheduling. | LOW |
concurrency | int | ConcurrencyExpression | list[ConcurrencyExpression] | None | A concurrency object controlling the concurrency settings for this 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 |
schedule_timeout | Duration | The maximum time allowed for scheduling the task. | timedelta(minutes=5) |
execution_timeout | Duration | The maximum time allowed for executing the task. | timedelta(seconds=60) |
retries | int | The number of times to retry the task before failing. | 0 |
rate_limits | list[RateLimit] | None | A list of rate limit configurations for the task. | None |
desired_worker_labels | dict[str, DesiredWorkerLabel] | list[DesiredWorkerLabel] | None | A dictionary of desired worker labels that determine to which worker the task should be assigned. | None |
backoff_factor | float | None | The backoff factor for controlling exponential backoff in retries. | None |
backoff_max_seconds | int | None | The maximum number of seconds to allow retries with exponential backoff to continue. | None |
default_filters | list[DefaultFilter] | None | A list of filters to create with the task is created. Note that this is a helper to allow you to create filters "declaratively" without needing to make a separate API call once the task is created to create them. | None |
default_additional_metadata | JSONSerializableMapping | None | A dictionary of additional metadata to attach to each run of this task by default. | None |
slot_cost | int | None | The 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 |
idempotency | TTLBasedIdempotencyConfig | StatusBasedIdempotencyConfig | None | An optional idempotency configuration for the task, controlling how Hatchet should determine if two runs of this task are "the same" for the purposes of deduplication and idempotent execution. | None |
Returns:
| Type | Description |
|---|---|
Callable[[Callable[Concatenate[EmptyModel, Context, P], R | CoroutineLike[R]]], Standalone[EmptyModel, R]] | Callable[[Callable[Concatenate[TWorkflowInput, Context, P], R | CoroutineLike[R]]], Standalone[TWorkflowInput, R]] | A decorator which creates a Standalone task object. |
durable_task
A decorator to transform a function into a standalone Hatchet durable task that runs as part of a workflow.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name | str | None | The name of the task. If not specified, defaults to the name of the function being wrapped by the task decorator. | None |
description | str | None | An optional description for the task. | None |
input_validator | type[TWorkflowInput] | None | A Pydantic model to use as a validator for the input to the task. If no validator is provided, defaults to an EmptyModel. | None |
on_events | list[str] | None | A list of event triggers for the task - events which cause the task to be run. | None |
on_crons | list[str] | None | A list of cron triggers for the task. | None |
cron_input | TWorkflowInput | None | An optional input to provide to runs triggered by the task's on_crons schedules. Should be an instance of the task's input model. | None |
version | str | None | A version for the task. | None |
sticky | StickyStrategy | None | A sticky strategy for the task. | None |
default_priority | int | Priority | The priority of the task. Higher values will cause this task to have priority in scheduling. | LOW |
concurrency | int | ConcurrencyExpression | list[ConcurrencyExpression] | None | A concurrency object controlling the concurrency settings for this 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 |
schedule_timeout | Duration | The maximum time allowed for scheduling the task. | timedelta(minutes=5) |
execution_timeout | Duration | The maximum time allowed for executing the task. | timedelta(seconds=60) |
retries | int | The number of times to retry the task before failing. | 0 |
rate_limits | list[RateLimit] | None | A list of rate limit configurations for the task. | None |
desired_worker_labels | dict[str, DesiredWorkerLabel] | list[DesiredWorkerLabel] | None | A dictionary of desired worker labels that determine to which worker the task should be assigned. | None |
backoff_factor | float | None | The backoff factor for controlling exponential backoff in retries. | None |
backoff_max_seconds | int | None | The maximum number of seconds to allow retries with exponential backoff to continue. | None |
default_filters | list[DefaultFilter] | None | A list of filters to create with the task is created. Note that this is a helper to allow you to create filters "declaratively" without needing to make a separate API call once the task is created to create them. | None |
default_additional_metadata | JSONSerializableMapping | None | A dictionary of additional metadata to attach to each run of this task by default. | None |
eviction_policy | EvictionPolicy | None | An optional eviction policy controlling when idle durable tasks are evicted from workers. | DEFAULT_DURABLE_TASK_EVICTION_POLICY |
idempotency | TTLBasedIdempotencyConfig | StatusBasedIdempotencyConfig | None | An optional idempotency configuration for the task, controlling how Hatchet should determine if two runs of this task are "the same" for the purposes of deduplication and idempotent execution. | None |
Returns:
| Type | Description |
|---|---|
Callable[[Callable[Concatenate[EmptyModel, DurableContext, P], R | CoroutineLike[R]]], Standalone[EmptyModel, R]] | Callable[[Callable[Concatenate[TWorkflowInput, DurableContext, P], R | CoroutineLike[R]]], Standalone[TWorkflowInput, R]] | A decorator which creates a Standalone task object. |
from_embedded classmethod
Run a full Hatchet engine locally and return a client wired to it.
No API token and no Docker required, which makes this the fastest way
to run Hatchet for local development. The engine runs as the
hatchet-embedded sidecar process (downloaded on first use) and starts
a bundled Postgres by default; set database_url on config.embedded
to use your own Postgres instead. You can read more about the embedded
engine in the docs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config | ClientConfig | None | Base client configuration to use; the connection fields (token, tenant, addresses, TLS) are overridden to point at the embedded engine. Set config.embedded (an EmbeddedHatchetConfig) to configure the embedded engine itself (e.g. database URL, ports). | None |
Returns:
| Type | Description |
|---|---|
Hatchet | A Hatchet client instance connected to the embedded engine. |
stop_embedded
Gracefully stop the embedded engine started by Hatchet.from_embedded().
Blocks until the engine has fully exited, including its bundled
Postgres. The embedded engine is process-wide: every client created
via Hatchet.from_embedded() in this process shares it. Call this
before your process exits so the engine's shutdown output does not
print after your program has returned. No-op when no embedded engine
is running in this process.
aio_stop_embedded
Async variant of stop_embedded.
Gracefully stops the embedded engine without blocking the event loop, and returns once the engine has fully exited. No-op when no embedded engine is running in this process.
Embedded Engine Configuration
Bases: BaseSettings
Configuration for the embedded Hatchet engine started by Hatchet.from_embedded().
Set it on ClientConfig.embedded. Every field can also be set via an environment
variable prefixed with HATCHET_CLIENT_EMBEDDED_, e.g. HATCHET_CLIENT_EMBEDDED_DATABASE_URL.
You can read more about the embedded engine in the docs.
Fields:
| Name | Type | Description |
|---|---|---|
version | str | None | The hatchet-embedded release tag to download. Defaults to the latest release. Tags correspond to the Hatchet engine version baked into the sidecar, so pinning this pins the engine. |
binary_path | str | None | Path to an existing sidecar binary. When set, the download is skipped. |
checksum | str | None | The expected sha256 hex digest of the sidecar binary. When set, it replaces the release's checksums.txt as the trust anchor, so a compromised release channel cannot substitute the binary. Pin it together with version. |
database_url | str | None | Connection string for an existing Postgres to use instead of the bundled one. |
postgres_data_dir | str | None | Directory to store the bundled Postgres runtime and data under. Defaults to a per-project directory derived from the working directory. |
grpc_port | int | None | Override the port the embedded engine's gRPC server listens on. |
api_port | int | None | Override the port the embedded REST API listens on. |
start_api | bool | Set to False to start only the engine and gRPC server, without the REST API. |
run_migrations | bool | Set to False to skip running database migrations on startup. |
rabbitmq_url | str | None | Connection string for a RabbitMQ instance to use as the message queue instead of Postgres. |
log_level | str | None | Log level for the embedded engine. |
ready_timeout_seconds | float | How long to wait, in seconds, for the embedded engine to become ready before raising an error. Defaults to 300 seconds. |
Last updated on September 1, 2026