RunsTypeScript SDK
Runs Client
The runs client is a client for interacting with task and workflow runs within Hatchet.
Methods
branchDurableTask()
Fork (reset) a durable task from a specific node, triggering re-execution from that point.
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
taskExternalId | string | undefined | The external ID of the durable task to reset. |
nodeId | number | undefined | The node ID to replay from. |
branchId | number | 0 | - |
Returns
Promise<AxiosResponse<V1BranchDurableTaskResponse, any, {
}>>
cancel()
Cancels a task or workflow run by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
opts | CancelRunOpts | The options for the cancel operation. |
Returns
Promise<AxiosResponse<V1CancelledTasks, any, {
}>>
A promise that resolves to the cancelled run.
get()
Gets a task or workflow run by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
run | string | WorkflowRunRef<T> | The ID of the run to get. |
Returns
Promise<V1WorkflowRunDetails>
A promise that resolves to the run.
get_status()
Gets the status of a task or workflow run by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
run | string | WorkflowRunRef<T> | The ID of the run to get the status of. |
Returns
Promise<V1TaskStatus>
A promise that resolves to the status of the run.
getDetails()
Gets run details
Parameters
| Parameter | Type | Description |
|---|---|---|
run | string | WorkflowRunRef<T> | The workflow run ID (string) or a WorkflowRunRef. |
Returns
Promise<RunDetail>
A promise resolving to GetRunDetailsResponse with task run statuses and outputs.
getTaskExternalId()
Resolve the task external ID for a workflow run. For runs with multiple tasks, returns the first task's external ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
workflowRunId | string | The workflow run ID to look up. |
Returns
Promise<string>
The task external ID.
list()
Lists all task and workflow runs for the current tenant.
Parameters
| Parameter | Type | Description |
|---|---|---|
opts? | Partial<ListRunsOpts> | The options for the list operation. |
Returns
Promise<V1TaskSummaryList>
A promise that resolves to the list of runs.
replay()
Replays a task or workflow run by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
opts | ReplayRunOpts | The options for the replay operation. |
Returns
Promise<AxiosResponse<V1ReplayedTasks, any, {
}>>
A promise that resolves to the replayed run.
restoreTask()
Restore an evicted durable task so it can resume execution.
Parameters
| Parameter | Type | Description |
|---|---|---|
taskExternalId | string | The external ID of the evicted task. |
Returns
Promise<AxiosResponse<V1RestoreTaskResponse, any, {
}>>
subscribeToStream()
Subscribes to a stream of events for a task or workflow run by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
workflowRunId | string | The ID of the run to subscribe to. |
Returns
AsyncIterableIterator<string>
A promise that resolves to the stream of events.
Type Aliases
RunDetail
type RunDetail = object;The state of a run, as GetRunDetails reports it. taskRuns is keyed by readable id.
TaskRunDetail
type TaskRunDetail = object;The state of one task of a run, as GetRunDetails reports it.
Properties
Last updated on October 1, 2026