Hatchet Go SDK Reference
This is the Go SDK reference, documenting methods available for interacting with Hatchet resources. Check out the user guide for an introduction for getting your first tasks running. For complete, generated API documentation, see the Go package docs on pkg.go.dev.
By default, the client reads its configuration (token, host, TLS settings, and so on) from the HATCHET_CLIENT_* environment variables. Configuration can be overridden with client options from the github.com/hatchet-dev/hatchet/pkg/client package, such as WithToken, WithHostPort, and WithNamespace.
Client
Client provides the main interface for interacting with Hatchet.
Methods:
| Name | Description |
|---|---|
Close | Close shuts down the client. |
Events | Events returns a client for sending and managing events. |
GetEngineVersion | GetEngineVersion retrieves the engine version from the server. |
NewStandaloneBatchTask | NewStandaloneBatchTask creates a standalone batch task that can be triggered independently. |
NewStandaloneDurableTask | NewStandaloneDurableTask creates a standalone durable task that can be triggered independently. |
NewStandaloneTask | NewStandaloneTask creates a standalone task that can be triggered independently. |
NewWorker | NewWorker creates a worker that can execute workflows. |
NewWorkflow | NewWorkflow creates a new workflow definition. |
Run | Run executes a workflow with the provided input and waits for completion. |
RunMany | RunMany executes multiple workflow instances with different inputs. |
RunNoWait | RunNoWait executes a workflow with the provided input without waiting for completion. |
Feature clients
The client exposes lazily-initialized feature clients as methods:
CEL()
CEL returns a client for working with CEL expressions. See the CEL client.
Crons()
Crons returns a client for managing cron triggers. See the Crons client.
Filters()
Filters returns a client for managing event filters. See the Filters client.
Logs()
Logs returns a client for managing task logs. See the Logs client.
Metrics()
Metrics returns a feature client for interacting with workflow and task metrics. See the Metrics client.
RateLimits()
RateLimits returns a client for managing rate limits. See the Rate Limits client.
Runs()
Runs returns a client for managing workflow runs. See the Runs client.
Schedules()
Schedules returns a client for managing scheduled workflow runs. See the Schedules client.
Webhooks()
Webhooks returns a client for managing webhooks. See the Webhooks client.
Workers()
Workers returns a client for managing workers. See the Workers client.
Workflows()
Workflows returns a client for managing workflow definitions. See the Workflows client.
Functions
NewClient
NewClient creates a new Hatchet client. Configuration options can be provided to customize the client behavior.
func NewClient(opts ...client.ClientOpt) (*Client, error)Parameters:
| Name | Type |
|---|---|
opts | ...client.ClientOpt |
Returns:
| Type |
|---|
*Client |
error |
Close
Close shuts down the client. It is a no-op unless the client runs in embedded mode, in which case it shuts down the in-process engine.
func (c *Client) Close(ctx context.Context) errorParameters:
| Name | Type |
|---|---|
ctx | context.Context |
Returns:
| Type |
|---|
error |
Events
Events returns a client for sending and managing events.
func (c *Client) Events() client.EventClientReturns:
| Type |
|---|
client.EventClient |
GetEngineVersion
GetEngineVersion retrieves the engine version from the server.
func (c *Client) GetEngineVersion(ctx context.Context) (string, error)Parameters:
| Name | Type |
|---|---|
ctx | context.Context |
Returns:
| Type |
|---|
string |
error |
NewStandaloneBatchTask
NewStandaloneBatchTask creates a standalone batch task that can be triggered independently. This is a specialized workflow containing only one batch task, making it easier to create simple single-task workflows without the workflow boilerplate.
The function parameter must have the signature:
func(ctx hatchet.Context, input map[string]T) (map[string]R, error)or, when batch.BroadcastOutput is true:
func(ctx hatchet.Context, input map[string]T) (R, error)Function signatures are validated at runtime using reflection.
Options can be any combination of WorkflowOption and TaskOption.
Preview: batch tasks are in beta and may change in future releases.
func (c *Client) NewStandaloneBatchTask(name string, fn any, batch BatchConfig, options ...StandaloneTaskOption) *StandaloneTaskParameters:
| Name | Type |
|---|---|
name | string |
fn | any |
batch | BatchConfig |
options | ...StandaloneTaskOption |
Returns:
| Type |
|---|
*StandaloneTask |
NewStandaloneDurableTask
NewStandaloneDurableTask creates a standalone durable task that can be triggered independently. This is a specialized workflow containing only one durable task, making it easier to create simple single-task workflows with durable functionality.
The function parameter must have the signature:
func(ctx hatchet.DurableContext, input any) (any, error)Function signatures are validated at runtime using reflection.
Options can be any combination of WorkflowOption and TaskOption.
func (c *Client) NewStandaloneDurableTask(name string, fn any, options ...StandaloneTaskOption) *StandaloneTaskParameters:
| Name | Type |
|---|---|
name | string |
fn | any |
options | ...StandaloneTaskOption |
Returns:
| Type |
|---|
*StandaloneTask |
NewStandaloneTask
NewStandaloneTask creates a standalone task that can be triggered independently. This is a specialized workflow containing only one task, making it easier to create simple single-task workflows without the workflow boilerplate.
The function parameter must have the signature:
func(ctx hatchet.Context, input any) (any, error)Function signatures are validated at runtime using reflection.
Options can be any combination of WorkflowOption and TaskOption.
func (c *Client) NewStandaloneTask(name string, fn any, options ...StandaloneTaskOption) *StandaloneTaskParameters:
| Name | Type |
|---|---|
name | string |
fn | any |
options | ...StandaloneTaskOption |
Returns:
| Type |
|---|
*StandaloneTask |
NewWorker
NewWorker creates a worker that can execute workflows.
func (c *Client) NewWorker(name string, options ...WorkerOption) (*Worker, error)Parameters:
| Name | Type |
|---|---|
name | string |
options | ...WorkerOption |
Returns:
| Type |
|---|
*Worker |
error |
NewWorkflow
NewWorkflow creates a new workflow definition. Workflows can be configured with triggers, events, and other options.
func (c *Client) NewWorkflow(name string, options ...WorkflowOption) *WorkflowParameters:
| Name | Type |
|---|---|
name | string |
options | ...WorkflowOption |
Returns:
| Type |
|---|
*Workflow |
Run
Run executes a workflow with the provided input and waits for completion.
func (c *Client) Run(ctx context.Context, workflowName string, input any, opts ...RunOptFunc) (*WorkflowResult, error)Parameters:
| Name | Type |
|---|---|
ctx | context.Context |
workflowName | string |
input | any |
opts | ...RunOptFunc |
Returns:
| Type |
|---|
*WorkflowResult |
error |
RunMany
RunMany executes multiple workflow instances with different inputs. Returns workflow run IDs that can be used to track the run statuses.
func (c *Client) RunMany(ctx context.Context, workflowName string, inputs []RunManyOpt) ([]WorkflowRunRef, error)Parameters:
| Name | Type |
|---|---|
ctx | context.Context |
workflowName | string |
inputs | []RunManyOpt |
Returns:
| Type |
|---|
[]WorkflowRunRef |
error |
RunNoWait
RunNoWait executes a workflow with the provided input without waiting for completion. Returns a workflow run reference that can be used to track the run status.
func (c *Client) RunNoWait(ctx context.Context, workflowName string, input any, opts ...RunOptFunc) (*WorkflowRunRef, error)Parameters:
| Name | Type |
|---|---|
ctx | context.Context |
workflowName | string |
input | any |
opts | ...RunOptFunc |
Returns:
| Type |
|---|
*WorkflowRunRef |
error |
Worker
Worker represents a worker that can execute workflows.
Methods:
| Name | Description |
|---|---|
Start | Starts the worker instance and returns a cleanup function. |
StartBlocking | StartBlocking starts the worker and blocks until it completes. |
Use | Use registers middleware functions on the worker. |
Functions
Start
Starts the worker instance and returns a cleanup function.
func (w *Worker) Start() (func() error, error)Returns:
| Type |
|---|
func() error |
error |
StartBlocking
StartBlocking starts the worker and blocks until it completes. This is a convenience method for common usage patterns.
func (w *Worker) StartBlocking(ctx context.Context) errorParameters:
| Name | Type |
|---|---|
ctx | context.Context |
Returns:
| Type |
|---|
error |
Use
Use registers middleware functions on the worker. Middleware functions are called in order for each step run execution.
func (w *Worker) Use(mws ...worker.MiddlewareFunc)Parameters:
| Name | Type |
|---|---|
mws | ...worker.MiddlewareFunc |
Worker options
Options for Client.NewWorker:
| Name | Signature | Description |
|---|---|---|
WithDurableSlots | WithDurableSlots(durableSlots int) | WithDurableSlots sets the maximum number of concurrent durable task runs. |
WithLabels | WithLabels(labels map[string]any) | WithLabels assigns labels to the worker for task routing. |
WithLogger | WithLogger(logger *zerolog.Logger) | WithLogger sets a custom logger for the worker. |
WithPanicHandler | WithPanicHandler(panicHandler func(ctx Context, recovered any)) | WithPanicHandler sets a custom panic handler for the worker. |
WithSlots | WithSlots(slots int) | WithSlots sets the maximum number of concurrent workflow runs. |
WithWorkflows | WithWorkflows(workflows ...WorkflowBase) | WithWorkflows registers workflows and standalone tasks with the worker. |
Last updated on August 24, 2026