Skip to main content
The History Service is the core component of Temporal Server that manages workflow execution state, history events, and orchestrates workflow execution lifecycle.

​
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.
​
namespace_id
string
required
UUID of the namespace
​
start_request
StartWorkflowExecutionRequest
required
Workflow start parameters including workflow_id, workflow_type, task_queue
​
parent_execution_info
ParentExecutionInfo
Information about parent workflow if this is a child workflow
​
run_id
string
Unique identifier for the workflow execution run
​
started
bool
True if a new execution was started, false if existing execution was found

​
TerminateWorkflowExecution

Terminates a running workflow execution.
​
namespace_id
string
required
Namespace UUID
​
terminate_request
TerminateWorkflowExecutionRequest
required
Contains workflow execution identifier and termination reason
​
response
TerminateWorkflowExecutionResponse
Empty response on success

​
DeleteWorkflowExecution

Deletes a workflow execution.
​
namespace_id
string
required
Namespace UUID
​
workflow_execution
WorkflowExecution
required
Workflow execution to delete
​
response
DeleteWorkflowExecutionResponse
Empty response on success

​
ResetWorkflowExecution

Resets a workflow execution to a specific point in history.
​
namespace_id
string
required
Namespace UUID
​
reset_request
ResetWorkflowExecutionRequest
required
Reset parameters including target event ID or reset type
​
run_id
string
New run ID for the reset execution

​
DescribeWorkflowExecution

Retrieves detailed information about a workflow execution.
​
namespace_id
string
required
Namespace UUID
​
request
DescribeWorkflowExecutionRequest
required
Contains workflow execution identifier
​
workflow_execution_info
WorkflowExecutionInfo
Execution metadata and current state
​
pending_activities
PendingActivityInfo[]
List of pending activities
​
pending_children
PendingChildExecutionInfo[]
List of pending child workflows

​
State Management

​
GetMutableState

Retrieves the mutable state of a workflow execution.
​
namespace_id
string
required
Namespace UUID
​
execution
WorkflowExecution
required
Workflow execution identifier
​
expected_next_event_id
int64
Expected next event ID for validation
​
execution
WorkflowExecution
Workflow execution details
​
workflow_type
WorkflowType
Type of the workflow
​
next_event_id
int64
Next event ID to be assigned
​
current_branch_token
bytes
Token for the current history branch

​
PollMutableState

Polls for mutable state changes with long polling support.
​
namespace_id
string
required
Namespace UUID
​
execution
WorkflowExecution
required
Workflow execution identifier
​
expected_next_event_id
int64
required
Expected next event ID
​
mutable_state
MutableState
Current mutable state if changed

​
DescribeMutableState

Returns comprehensive mutable state information for debugging.
​
namespace_id
string
required
Namespace UUID
​
execution
WorkflowExecution
required
Workflow execution identifier
​
cache_mutable_state_info
string
JSON representation of cached state
​
database_mutable_state
object
Mutable state from database

​
Workflow Task Management

​
RecordWorkflowTaskStarted

Records that a workflow task has started processing.
​
namespace_id
string
required
Namespace UUID
​
workflow_execution
WorkflowExecution
required
Workflow execution identifier
​
scheduled_event_id
int64
required
Event ID of the workflow task scheduled event
​
request_id
string
required
Unique request ID for idempotency
​
poll_request
PollWorkflowTaskQueueRequest
required
Original poll request information
​
workflow_type
WorkflowType
Type of the workflow
​
started_event_id
int64
Event ID of the started event
​
attempt
int32
Current attempt number
​
history
History
History events for the task

​
RespondWorkflowTaskCompleted

Records completion of a workflow task with generated commands.
​
namespace_id
string
required
Namespace UUID
​
complete_request
RespondWorkflowTaskCompletedRequest
required
Contains task token and workflow commands
​
workflow_task
WorkflowTaskInfo
Information about any new workflow task generated
​
activity_tasks
ActivityTaskInfo[]
New activity tasks generated

​
RespondWorkflowTaskFailed

Records that a workflow task failed.
​
namespace_id
string
required
Namespace UUID
​
failed_request
RespondWorkflowTaskFailedRequest
required
Contains task token and failure details
​
response
RespondWorkflowTaskFailedResponse
Empty response on success

​
IsWorkflowTaskValid

Validates if a workflow task is still valid.
​
namespace_id
string
required
Namespace UUID
​
execution
WorkflowExecution
required
Workflow execution identifier
​
scheduled_event_id
int64
required
Scheduled event ID to validate
​
is_valid
bool
Whether the task is still valid

​
Activity Task Management

​
RecordActivityTaskStarted

Records that an activity task has started.
​
namespace_id
string
required
Namespace UUID
​
workflow_execution
WorkflowExecution
required
Workflow execution identifier
​
scheduled_event_id
int64
required
Event ID when activity was scheduled
​
request_id
string
required
Unique request ID
​
scheduled_event
HistoryEvent
The activity scheduled event
​
started_event_id
int64
Event ID for the started event
​
attempt
int32
Current attempt number

​
RecordActivityTaskHeartbeat

Records a heartbeat for a running activity.
​
namespace_id
string
required
Namespace UUID
​
heartbeat_request
RecordActivityTaskHeartbeatRequest
required
Contains task token and heartbeat details
​
cancel_requested
bool
Whether the activity has been requested to cancel

​
RespondActivityTaskCompleted

Records successful completion of an activity task.
​
namespace_id
string
required
Namespace UUID
​
complete_request
RespondActivityTaskCompletedRequest
required
Contains task token and result
​
response
RespondActivityTaskCompletedResponse
Empty response on success

​
RespondActivityTaskFailed

Records failure of an activity task.
​
namespace_id
string
required
Namespace UUID
​
failed_request
RespondActivityTaskFailedRequest
required
Contains task token and failure details
​
response
RespondActivityTaskFailedResponse
Empty response on success

​
RespondActivityTaskCanceled

Records cancellation of an activity task.
​
namespace_id
string
required
Namespace UUID
​
canceled_request
RespondActivityTaskCanceledRequest
required
Contains task token and cancellation details
​
response
RespondActivityTaskCanceledResponse
Empty response on success

​
Signals and Queries

​
SignalWorkflowExecution

Sends a signal to a workflow execution.
​
namespace_id
string
required
Namespace UUID
​
signal_request
SignalWorkflowExecutionRequest
required
Contains execution identifier, signal name, and input
​
response
SignalWorkflowExecutionResponse
Empty response on success

​
SignalWithStartWorkflowExecution

Signals a workflow or starts it if it doesn’t exist.
​
namespace_id
string
required
Namespace UUID
​
signal_with_start_request
SignalWithStartWorkflowExecutionRequest
required
Combined signal and start parameters
​
run_id
string
Run ID of the signaled or started workflow

​
QueryWorkflow

Executes a query against a workflow execution.
​
namespace_id
string
required
Namespace UUID
​
request
QueryWorkflowRequest
required
Contains execution identifier and query details
​
query_result
Payloads
Result of the query
​
query_rejected
QueryRejected
Query rejection details if rejected

​
RemoveSignalMutableState

Removes a signal from the mutable state.
​
namespace_id
string
required
Namespace UUID
​
workflow_execution
WorkflowExecution
required
Workflow execution identifier
​
request_id
string
required
Request ID of the signal to remove

​
Workflow Updates

​
UpdateWorkflowExecution

Executes an update on a workflow execution.
​
namespace_id
string
required
Namespace UUID
​
update_request
UpdateWorkflowExecutionRequest
required
Update request with update name and arguments
​
update_ref
UpdateRef
Reference to the update for polling
​
outcome
Outcome
Update outcome if completed synchronously

​
PollWorkflowExecutionUpdate

Polls for the result of a workflow update.
​
namespace_id
string
required
Namespace UUID
​
update_ref
UpdateRef
required
Reference to the update
​
outcome
Outcome
Update outcome (success or failure)

​
History Operations

​
GetWorkflowExecutionHistory

Retrieves workflow execution history.
​
namespace_id
string
required
Namespace UUID
​
request
GetWorkflowExecutionHistoryRequest
required
Contains execution identifier and pagination parameters
​
history
History
History events
​
next_page_token
bytes
Token for next page
​
archived
bool
Whether history is from archive

​
GetWorkflowExecutionHistoryReverse

Retrieves workflow history in reverse order.
​
namespace_id
string
required
Namespace UUID
​
request
GetWorkflowExecutionHistoryReverseRequest
required
Request parameters
​
history
History
History events in reverse order
​
next_page_token
bytes
Token for next page

​
GetWorkflowExecutionRawHistoryV2

Retrieves raw history events as encoded blobs.
​
namespace_id
string
required
Namespace UUID
​
request
GetWorkflowExecutionRawHistoryV2Request
required
Request with pagination parameters
​
history_batches
DataBlob[]
Raw history batches
​
next_page_token
bytes
Pagination token

​
Replication

​
ReplicateEventsV2

Replicates history events from another cluster.
​
namespace_id
string
required
Namespace UUID
​
workflow_execution
WorkflowExecution
required
Target workflow execution
​
events
VersionHistoryItem[]
required
Events to replicate
​
response
ReplicateEventsV2Response
Empty response on success

​
ReplicateWorkflowState

Replicates complete workflow state.
​
workflow_state
WorkflowState
required
Complete workflow state to replicate
​
response
ReplicateWorkflowStateResponse
Empty response on success

​
GetReplicationMessages

Retrieves replication messages for a shard.
​
tokens
ReplicationToken[]
required
Tokens indicating last received messages
​
cluster_name
string
required
Source cluster name
​
replication_tasks
ReplicationTask[]
Batch of replication tasks

​
Child Workflow Management

​
RecordChildExecutionCompleted

Records completion of a child workflow.
​
namespace_id
string
required
Namespace UUID of parent workflow
​
parent_execution
WorkflowExecution
required
Parent workflow execution
​
parent_initiated_id
int64
required
Event ID when child was initiated
​
completion_event
HistoryEvent
required
Child completion event

​
Additional Operations

​
ScheduleWorkflowTask

Schedules a new workflow task.
​
namespace_id
string
required
Namespace UUID
​
workflow_execution
WorkflowExecution
required
Workflow execution identifier
​
is_first_workflow_task
bool
Whether this is the first task

​
ResetStickyTaskQueue

Resets the sticky task queue for a workflow.
​
namespace_id
string
required
Namespace UUID
​
execution
WorkflowExecution
required
Workflow execution identifier
​
response
ResetStickyTaskQueueResponse
Empty response on success

​
RequestCancelWorkflowExecution

Requests cancellation of a workflow execution.
​
namespace_id
string
required
Namespace UUID
​
cancel_request
RequestCancelWorkflowExecutionRequest
required
Cancellation request details
​
response
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

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us