Workflows ClientRuby SDK
Workflows client for managing workflow definitions within Hatchet.
Note that workflows are the declaration, not the individual runs. If you're looking for runs, use the Runs client instead.
workflow = hatchet.workflows.get("workflow-id")workflows = hatchet.workflows.list(workflow_name: "my-workflow", limit: 10)It is available on the main client as hatchet.workflows.
Methods:
| Name | Description |
|---|---|
get | Get a workflow by its ID. |
list | List all workflows in the tenant matching optional filters. |
get_version | Get a workflow version by the workflow ID and an optional version. |
delete | Permanently delete a workflow. |
pause | Pause a workflow. |
unpause | Unpause a workflow. |
Functions
get
Get a workflow by its ID.
workflow = hatchet.workflows.get("workflow-123")Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_id | String | The ID of the workflow to retrieve. | required |
Returns:
| Type | Description |
|---|---|
Object | The workflow details. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
list
List all workflows in the tenant matching optional filters.
workflows = hatchet.workflows.list(workflow_name: "my-workflow", limit: 10, offset: 0)Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_name | String | nil | The name of the workflow to filter by (namespace will be applied) | nil |
limit | Integer | nil | The maximum number of items to return. | nil |
offset | Integer | nil | The offset to start the list from. | nil |
Returns:
| Type | Description |
|---|---|
Object | A list of workflows. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
get_version
Get a workflow version by the workflow ID and an optional version.
version = hatchet.workflows.get_version("workflow-123", version: "v2")Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_id | String | The ID of the workflow to retrieve the version for. | required |
version | String | nil | The version to retrieve. If nil, the latest version is returned. | nil |
Returns:
| Type | Description |
|---|---|
Object | The workflow version. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
delete
Permanently delete a workflow.
DANGEROUS: This will delete a workflow and all of its data.
hatchet.workflows.delete("workflow-123")Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_id | String | The ID of the workflow to delete. | required |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
pause
Pause a workflow. While paused, new runs of the workflow are queued but not started.
hatchet.workflows.pause("workflow-123", queue_ttl: 3600)Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_id | String | The ID of the workflow to pause. | required |
queue_ttl | Integer | String | How long runs stay queued while the workflow is paused before they are dropped, in seconds or as a duration string (e.g. "1h30m") | required |
paused_workflow_cron_run_queue_behavior | String | The behavior of cron runs triggered while the workflow is paused ("QUEUE" or "DROP") | HatchetSdkRest::WorkflowPauseScheduledCronRunQueueBehavior::QUEUE |
paused_workflow_scheduled_run_queue_behavior | String | The behavior of scheduled runs triggered while the workflow is paused ("QUEUE" or "DROP") | HatchetSdkRest::WorkflowPauseScheduledCronRunQueueBehavior::QUEUE |
Returns:
| Type | Description |
|---|---|
HatchetSdkRest::Workflow | The updated workflow. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
unpause
Unpause a workflow.
hatchet.workflows.unpause("workflow-123")Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_id | String | The ID of the workflow to unpause. | required |
Returns:
| Type | Description |
|---|---|
HatchetSdkRest::Workflow | The updated workflow. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
Last updated on October 14, 2026