Overview
The History Service is responsible for:- Managing workflow execution mutable state
- Persisting and retrieving workflow history events
- Coordinating workflow task execution
- Managing activity task lifecycle
- Handling workflow signals and queries
- Executing workflow updates
- Managing child workflow executions
- Coordinating replication across clusters
Service Methods
Workflow Execution Lifecycle
StartWorkflowExecution
Starts a new workflow execution or signals an existing one.string
required
UUID of the namespace
StartWorkflowExecutionRequest
required
Workflow start parameters including workflow_id, workflow_type, task_queue
ParentExecutionInfo
Information about parent workflow if this is a child workflow
string
Unique identifier for the workflow execution run
bool
True if a new execution was started, false if existing execution was found
TerminateWorkflowExecution
Terminates a running workflow execution.string
required
Namespace UUID
TerminateWorkflowExecutionRequest
required
Contains workflow execution identifier and termination reason
TerminateWorkflowExecutionResponse
Empty response on success
DeleteWorkflowExecution
Deletes a workflow execution.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution to delete
DeleteWorkflowExecutionResponse
Empty response on success
ResetWorkflowExecution
Resets a workflow execution to a specific point in history.string
required
Namespace UUID
ResetWorkflowExecutionRequest
required
Reset parameters including target event ID or reset type
string
New run ID for the reset execution
DescribeWorkflowExecution
Retrieves detailed information about a workflow execution.string
required
Namespace UUID
DescribeWorkflowExecutionRequest
required
Contains workflow execution identifier
WorkflowExecutionInfo
Execution metadata and current state
PendingActivityInfo[]
List of pending activities
PendingChildExecutionInfo[]
List of pending child workflows
State Management
GetMutableState
Retrieves the mutable state of a workflow execution.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
int64
Expected next event ID for validation
WorkflowExecution
Workflow execution details
WorkflowType
Type of the workflow
int64
Next event ID to be assigned
bytes
Token for the current history branch
PollMutableState
Polls for mutable state changes with long polling support.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
int64
required
Expected next event ID
MutableState
Current mutable state if changed
DescribeMutableState
Returns comprehensive mutable state information for debugging.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
string
JSON representation of cached state
object
Mutable state from database
Workflow Task Management
RecordWorkflowTaskStarted
Records that a workflow task has started processing.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
int64
required
Event ID of the workflow task scheduled event
string
required
Unique request ID for idempotency
PollWorkflowTaskQueueRequest
required
Original poll request information
WorkflowType
Type of the workflow
int64
Event ID of the started event
int32
Current attempt number
History
History events for the task
RespondWorkflowTaskCompleted
Records completion of a workflow task with generated commands.string
required
Namespace UUID
RespondWorkflowTaskCompletedRequest
required
Contains task token and workflow commands
WorkflowTaskInfo
Information about any new workflow task generated
ActivityTaskInfo[]
New activity tasks generated
RespondWorkflowTaskFailed
Records that a workflow task failed.string
required
Namespace UUID
RespondWorkflowTaskFailedRequest
required
Contains task token and failure details
RespondWorkflowTaskFailedResponse
Empty response on success
IsWorkflowTaskValid
Validates if a workflow task is still valid.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
int64
required
Scheduled event ID to validate
bool
Whether the task is still valid
Activity Task Management
RecordActivityTaskStarted
Records that an activity task has started.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
int64
required
Event ID when activity was scheduled
string
required
Unique request ID
HistoryEvent
The activity scheduled event
int64
Event ID for the started event
int32
Current attempt number
RecordActivityTaskHeartbeat
Records a heartbeat for a running activity.string
required
Namespace UUID
RecordActivityTaskHeartbeatRequest
required
Contains task token and heartbeat details
bool
Whether the activity has been requested to cancel
RespondActivityTaskCompleted
Records successful completion of an activity task.string
required
Namespace UUID
RespondActivityTaskCompletedRequest
required
Contains task token and result
RespondActivityTaskCompletedResponse
Empty response on success
RespondActivityTaskFailed
Records failure of an activity task.string
required
Namespace UUID
RespondActivityTaskFailedRequest
required
Contains task token and failure details
RespondActivityTaskFailedResponse
Empty response on success
RespondActivityTaskCanceled
Records cancellation of an activity task.string
required
Namespace UUID
RespondActivityTaskCanceledRequest
required
Contains task token and cancellation details
RespondActivityTaskCanceledResponse
Empty response on success
Signals and Queries
SignalWorkflowExecution
Sends a signal to a workflow execution.string
required
Namespace UUID
SignalWorkflowExecutionRequest
required
Contains execution identifier, signal name, and input
SignalWorkflowExecutionResponse
Empty response on success
SignalWithStartWorkflowExecution
Signals a workflow or starts it if it doesn’t exist.string
required
Namespace UUID
SignalWithStartWorkflowExecutionRequest
required
Combined signal and start parameters
string
Run ID of the signaled or started workflow
QueryWorkflow
Executes a query against a workflow execution.string
required
Namespace UUID
QueryWorkflowRequest
required
Contains execution identifier and query details
Payloads
Result of the query
QueryRejected
Query rejection details if rejected
RemoveSignalMutableState
Removes a signal from the mutable state.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
string
required
Request ID of the signal to remove
Workflow Updates
UpdateWorkflowExecution
Executes an update on a workflow execution.string
required
Namespace UUID
UpdateWorkflowExecutionRequest
required
Update request with update name and arguments
UpdateRef
Reference to the update for polling
Outcome
Update outcome if completed synchronously
PollWorkflowExecutionUpdate
Polls for the result of a workflow update.string
required
Namespace UUID
UpdateRef
required
Reference to the update
Outcome
Update outcome (success or failure)
History Operations
GetWorkflowExecutionHistory
Retrieves workflow execution history.string
required
Namespace UUID
GetWorkflowExecutionHistoryRequest
required
Contains execution identifier and pagination parameters
History
History events
bytes
Token for next page
bool
Whether history is from archive
GetWorkflowExecutionHistoryReverse
Retrieves workflow history in reverse order.string
required
Namespace UUID
GetWorkflowExecutionHistoryReverseRequest
required
Request parameters
History
History events in reverse order
bytes
Token for next page
GetWorkflowExecutionRawHistoryV2
Retrieves raw history events as encoded blobs.string
required
Namespace UUID
GetWorkflowExecutionRawHistoryV2Request
required
Request with pagination parameters
DataBlob[]
Raw history batches
bytes
Pagination token
Replication
ReplicateEventsV2
Replicates history events from another cluster.string
required
Namespace UUID
WorkflowExecution
required
Target workflow execution
VersionHistoryItem[]
required
Events to replicate
ReplicateEventsV2Response
Empty response on success
ReplicateWorkflowState
Replicates complete workflow state.WorkflowState
required
Complete workflow state to replicate
ReplicateWorkflowStateResponse
Empty response on success
GetReplicationMessages
Retrieves replication messages for a shard.ReplicationToken[]
required
Tokens indicating last received messages
string
required
Source cluster name
ReplicationTask[]
Batch of replication tasks
Child Workflow Management
RecordChildExecutionCompleted
Records completion of a child workflow.string
required
Namespace UUID of parent workflow
WorkflowExecution
required
Parent workflow execution
int64
required
Event ID when child was initiated
HistoryEvent
required
Child completion event
Additional Operations
ScheduleWorkflowTask
Schedules a new workflow task.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
bool
Whether this is the first task
ResetStickyTaskQueue
Resets the sticky task queue for a workflow.string
required
Namespace UUID
WorkflowExecution
required
Workflow execution identifier
ResetStickyTaskQueueResponse
Empty response on success
RequestCancelWorkflowExecution
Requests cancellation of a workflow execution.string
required
Namespace UUID
RequestCancelWorkflowExecutionRequest
required
Cancellation request details
RequestCancelWorkflowExecutionResponse
Empty response on success
Usage Notes
- The History Service is typically called by Frontend Service, not directly by clients
- All operations use namespace UUIDs rather than names for efficiency
- Task tokens encode execution context for idempotent operations
- Long polling is supported for state change operations
- Replication operations are used in multi-cluster deployments