Skip to main content

​
Initializing the client

from hatchet_sdk import Hatchet

hatchet = Hatchet()
The Hatchet constructor accepts the following parameters:
​
debug
bool
default:"False"
Enable debug-level logging for the client and worker.
​
config
ClientConfig | None
default:"None"
A ClientConfig instance with explicit configuration. When None, the client reads configuration from environment variables and .env files.

​
ClientConfig

ClientConfig is a Pydantic settings model that can be constructed programmatically or populated from environment variables (prefixed with HATCHET_CLIENT_). 
from hatchet_sdk import ClientConfig, Hatchet

hatchet = Hatchet(
    config=ClientConfig(
        token="ey...",
        host_port="localhost:7070",
        namespace="my-app",
    )
)

​
Fields

​
token
str
required
Your Hatchet API token (a JWT). Required — the client will raise a ValueError if it is not set or is not a valid JWT.
​
host_port
str
default:"Read from token"
The gRPC server address, e.g. "localhost:7070". When not explicitly set, the value is read from the token’s embedded address.
​
namespace
str
default:"\"\""
A namespace prefix applied to all workflow names and event keys. The SDK appends a trailing underscore automatically — e.g. "myapp" becomes "myapp_". Set via HATCHET_CLIENT_NAMESPACE.
​
tenant_id
str
default:"Read from token"
The tenant ID. When not set, it is extracted from the JWT automatically.
​
tls_config
ClientTLSConfig
TLS settings. Configured via HATCHET_CLIENT_TLS_* environment variables. Key fields:
  • strategy — "tls" (default) or "none"
  • cert_file, key_file, root_ca_file — paths to certificate files
  • server_name — override the TLS server name (defaults to the host)
​
grpc_max_recv_message_length
int
default:"4194304"
Maximum gRPC receive message size in bytes. Default is 4 MB.
​
grpc_max_send_message_length
int
default:"4194304"
Maximum gRPC send message size in bytes. Default is 4 MB.

​
Feature client properties

All feature clients are exposed as properties on the Hatchet instance. Each client wraps a specific area of the Hatchet API.
PropertyTypeDescription
hatchet.runsRunsClientList, get, cancel, and replay task and workflow runs.
hatchet.cronCronClientCreate and manage cron workflow triggers.
hatchet.scheduledScheduledClientCreate and manage one-off scheduled workflow runs.
hatchet.webhooksWebhooksClientCreate and manage incoming webhook endpoints.
hatchet.workersWorkersClientList, get, pause, and unpause workers.
hatchet.workflowsWorkflowsClientList, get, and delete workflow declarations.
hatchet.eventEventClientPush events that trigger event-based workflows.
hatchet.logsLogsClientAccess run log lines.
hatchet.metricsMetricsClientRead Hatchet metrics.
hatchet.rate_limitsRateLimitsClientWork with rate limit configurations.
hatchet.celCELClientEvaluate CEL expressions against Hatchet’s CEL API.
hatchet.filtersFiltersClientCreate and manage workflow run filters.
See Feature clients for method-level documentation on each client.

​
Helper properties

# The tenant ID derived from the API token
hatchet.tenant_id  # str

# The configured namespace (e.g. "myapp_")
hatchet.namespace  # str

​
Getting context inside a task

Use hatchet.get_current_context() to retrieve the active Context from anywhere in the call stack during task execution: 
from hatchet_sdk import Context, EmptyModel, Hatchet

hatchet = Hatchet()

def some_helper_function() -> None:
    ctx = hatchet.get_current_context()
    if ctx is not None:
        ctx.log("called from inside a task")

@hatchet.task()
def my_task(input: EmptyModel, ctx: Context) -> None:
    some_helper_function()
get_current_context() returns None when called outside of task execution.

Build docs developers (and LLMs) love

Get started for freeTalk to us