Workflow Protocol - Management API

Low-level description of the Workflow building block internals.

Workflow Management API

The Workflow Management API allows Dapr clients to control the lifecycle of workflow instances. These APIs are exposed via the standard Dapr gRPC endpoint and are typically made available via the SDKs.

gRPC Service Definition

The management APIs are part of the Dapr service in dapr.proto.runtime.v1. While multiple versions (Alpha1, Beta1) may exist, the following describes the current implementation logic.

StartWorkflow

Starts a new instance of a workflow.

Request (StartWorkflowRequest):

Field	Type	Description
`instance_id`	`string`	Optional. A unique identifier for the workflow instance. If not provided, Dapr will generate a random UUID.
`workflow_component`	`string`	The name of the workflow component to use. Currently, Dapr uses the built-in engine.
`workflow_name`	`string`	The name of the workflow definition to execute.
`options`	`map<string, string>`	Optional. Component-specific options.
`input`	`bytes`	Optional. Input data for the workflow instance, typically a JSON-serialized string.

Response (StartWorkflowResponse):

Field	Type	Description
`instance_id`	`string`	The ID of the started workflow instance.

GetWorkflow

Retrieves the current status and metadata of a workflow instance.

Request (GetWorkflowRequest):

Field	Type	Description
`instance_id`	`string`	The ID of the workflow instance to query.
`workflow_component`	`string`	The name of the workflow component.

Response (GetWorkflowResponse):

Field	Type	Description
`instance_id`	`string`	The ID of the workflow instance.
`workflow_name`	`string`	The name of the workflow.
`created_at`	`Timestamp`	The time the instance was created.
`last_updated_at`	`Timestamp`	The time the instance was last updated.
`runtime_status`	`string`	The status (e.g., `RUNNING`, `COMPLETED`, `FAILED`, `TERMINATED`, `PENDING`).
`properties`	`map<string, string>`	Additional component-specific metadata.

TerminateWorkflow

Forcefully terminates a running workflow instance.

Request (TerminateWorkflowRequest):

Field	Type	Description
`instance_id`	`string`	The ID of the workflow instance to terminate.
`workflow_component`	`string`	The name of the workflow component.

RaiseEventWorkflow

Sends an event to a running workflow instance.

Request (RaiseEventWorkflowRequest):

Field	Type	Description
`instance_id`	`string`	The ID of the workflow instance.
`workflow_component`	`string`	The name of the workflow component.
`event_name`	`string`	The name of the event to raise.
`event_data`	`bytes`	The data associated with the event.

PauseWorkflow & ResumeWorkflow

Pauses or resumes a workflow instance.

Request (PauseWorkflowRequest / ResumeWorkflowRequest):

Field	Type	Description
`instance_id`	`string`	The ID of the workflow instance.
`workflow_component`	`string`	The name of the workflow component.

PurgeWorkflow

Removes all state and history associated with a workflow instance. This can usually only be done for completed, failed, or terminated instances.

Request (PurgeWorkflowRequest):

Field	Type	Description
`instance_id`	`string`	The ID of the workflow instance.
`workflow_component`	`string`	The name of the workflow component.

ListInstanceIDs (Task Hub Protocol Only)

Retrieves a list of workflow instance IDs, optionally filtered by status or name. This is currently part of the internal Task Hub protocol and used for pagination in management tools.

Request (ListInstanceIDsRequest):

Field	Type	Description
`page_size`	`int32`	The maximum number of IDs to return.
`continuation_token`	`string`	An opaque token used to retrieve the next page of results.

Response (ListInstanceIDsResponse):

Field	Type	Description
`instance_ids`	`repeated string`	The list of instance IDs.
`continuation_token`	`string`	A token for the next page of results.

Continuation Tokens and Pagination

The continuation_token is an opaque string generated by the Dapr runtime (and the underlying state store). Its purpose is to allow clients to reliably paginate through large sets of workflow instances without loading all IDs into memory at once.

SDK Requirements for Continuation Tokens:

Opaqueness: The SDK MUST treat this token as a black box. It should not attempt to parse, modify, or construct its own tokens.
State Management: When the SDK receives a ListInstanceIDsResponse, it should store the continuation_token if it intends to fetch more results.
Request Propagation: To fetch the next page, the SDK MUST pass the exact continuation_token received from the previous response into the next ListInstanceIDsRequest.
Termination: An empty or null continuation_token in the response indicates that there are no more pages to retrieve.

Runtime Behavior: The runtime derives this token from the state store’s KeysLike operation. Because it is tied to the underlying database’s pagination mechanism, the token may have an expiration or be tied to the specific query parameters (like page_size) used in the initial request.

Implementation Details

The sidecar receives these requests and translates them into operations on the underlying durabletask-go client. For example, StartWorkflow calls the backend to create a new orchestration instance and enqueue an ExecutionStarted event.

Last modified February 27, 2026: Merge pull request #5056 from marcduiker/release-v1.17 (67cd1a2)