> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# History Service API

> Core workflow execution management service

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.

<ParamField path="namespace_id" type="string" required>
  UUID of the namespace
</ParamField>

<ParamField path="start_request" type="StartWorkflowExecutionRequest" required>
  Workflow start parameters including workflow\_id, workflow\_type, task\_queue
</ParamField>

<ParamField path="parent_execution_info" type="ParentExecutionInfo">
  Information about parent workflow if this is a child workflow
</ParamField>

<ResponseField name="run_id" type="string">
  Unique identifier for the workflow execution run
</ResponseField>

<ResponseField name="started" type="bool">
  True if a new execution was started, false if existing execution was found
</ResponseField>

#### TerminateWorkflowExecution

Terminates a running workflow execution.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="terminate_request" type="TerminateWorkflowExecutionRequest" required>
  Contains workflow execution identifier and termination reason
</ParamField>

<ResponseField name="response" type="TerminateWorkflowExecutionResponse">
  Empty response on success
</ResponseField>

#### DeleteWorkflowExecution

Deletes a workflow execution.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Workflow execution to delete
</ParamField>

<ResponseField name="response" type="DeleteWorkflowExecutionResponse">
  Empty response on success
</ResponseField>

#### ResetWorkflowExecution

Resets a workflow execution to a specific point in history.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="reset_request" type="ResetWorkflowExecutionRequest" required>
  Reset parameters including target event ID or reset type
</ParamField>

<ResponseField name="run_id" type="string">
  New run ID for the reset execution
</ResponseField>

#### DescribeWorkflowExecution

Retrieves detailed information about a workflow execution.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="request" type="DescribeWorkflowExecutionRequest" required>
  Contains workflow execution identifier
</ParamField>

<ResponseField name="workflow_execution_info" type="WorkflowExecutionInfo">
  Execution metadata and current state
</ResponseField>

<ResponseField name="pending_activities" type="PendingActivityInfo[]">
  List of pending activities
</ResponseField>

<ResponseField name="pending_children" type="PendingChildExecutionInfo[]">
  List of pending child workflows
</ResponseField>

### State Management

#### GetMutableState

Retrieves the mutable state of a workflow execution.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ParamField path="expected_next_event_id" type="int64">
  Expected next event ID for validation
</ParamField>

<ResponseField name="execution" type="WorkflowExecution">
  Workflow execution details
</ResponseField>

<ResponseField name="workflow_type" type="WorkflowType">
  Type of the workflow
</ResponseField>

<ResponseField name="next_event_id" type="int64">
  Next event ID to be assigned
</ResponseField>

<ResponseField name="current_branch_token" type="bytes">
  Token for the current history branch
</ResponseField>

#### PollMutableState

Polls for mutable state changes with long polling support.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ParamField path="expected_next_event_id" type="int64" required>
  Expected next event ID
</ParamField>

<ResponseField name="mutable_state" type="MutableState">
  Current mutable state if changed
</ResponseField>

#### DescribeMutableState

Returns comprehensive mutable state information for debugging.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ResponseField name="cache_mutable_state_info" type="string">
  JSON representation of cached state
</ResponseField>

<ResponseField name="database_mutable_state" type="object">
  Mutable state from database
</ResponseField>

### Workflow Task Management

#### RecordWorkflowTaskStarted

Records that a workflow task has started processing.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ParamField path="scheduled_event_id" type="int64" required>
  Event ID of the workflow task scheduled event
</ParamField>

<ParamField path="request_id" type="string" required>
  Unique request ID for idempotency
</ParamField>

<ParamField path="poll_request" type="PollWorkflowTaskQueueRequest" required>
  Original poll request information
</ParamField>

<ResponseField name="workflow_type" type="WorkflowType">
  Type of the workflow
</ResponseField>

<ResponseField name="started_event_id" type="int64">
  Event ID of the started event
</ResponseField>

<ResponseField name="attempt" type="int32">
  Current attempt number
</ResponseField>

<ResponseField name="history" type="History">
  History events for the task
</ResponseField>

#### RespondWorkflowTaskCompleted

Records completion of a workflow task with generated commands.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="complete_request" type="RespondWorkflowTaskCompletedRequest" required>
  Contains task token and workflow commands
</ParamField>

<ResponseField name="workflow_task" type="WorkflowTaskInfo">
  Information about any new workflow task generated
</ResponseField>

<ResponseField name="activity_tasks" type="ActivityTaskInfo[]">
  New activity tasks generated
</ResponseField>

#### RespondWorkflowTaskFailed

Records that a workflow task failed.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="failed_request" type="RespondWorkflowTaskFailedRequest" required>
  Contains task token and failure details
</ParamField>

<ResponseField name="response" type="RespondWorkflowTaskFailedResponse">
  Empty response on success
</ResponseField>

#### IsWorkflowTaskValid

Validates if a workflow task is still valid.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ParamField path="scheduled_event_id" type="int64" required>
  Scheduled event ID to validate
</ParamField>

<ResponseField name="is_valid" type="bool">
  Whether the task is still valid
</ResponseField>

### Activity Task Management

#### RecordActivityTaskStarted

Records that an activity task has started.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ParamField path="scheduled_event_id" type="int64" required>
  Event ID when activity was scheduled
</ParamField>

<ParamField path="request_id" type="string" required>
  Unique request ID
</ParamField>

<ResponseField name="scheduled_event" type="HistoryEvent">
  The activity scheduled event
</ResponseField>

<ResponseField name="started_event_id" type="int64">
  Event ID for the started event
</ResponseField>

<ResponseField name="attempt" type="int32">
  Current attempt number
</ResponseField>

#### RecordActivityTaskHeartbeat

Records a heartbeat for a running activity.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="heartbeat_request" type="RecordActivityTaskHeartbeatRequest" required>
  Contains task token and heartbeat details
</ParamField>

<ResponseField name="cancel_requested" type="bool">
  Whether the activity has been requested to cancel
</ResponseField>

#### RespondActivityTaskCompleted

Records successful completion of an activity task.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="complete_request" type="RespondActivityTaskCompletedRequest" required>
  Contains task token and result
</ParamField>

<ResponseField name="response" type="RespondActivityTaskCompletedResponse">
  Empty response on success
</ResponseField>

#### RespondActivityTaskFailed

Records failure of an activity task.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="failed_request" type="RespondActivityTaskFailedRequest" required>
  Contains task token and failure details
</ParamField>

<ResponseField name="response" type="RespondActivityTaskFailedResponse">
  Empty response on success
</ResponseField>

#### RespondActivityTaskCanceled

Records cancellation of an activity task.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="canceled_request" type="RespondActivityTaskCanceledRequest" required>
  Contains task token and cancellation details
</ParamField>

<ResponseField name="response" type="RespondActivityTaskCanceledResponse">
  Empty response on success
</ResponseField>

### Signals and Queries

#### SignalWorkflowExecution

Sends a signal to a workflow execution.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="signal_request" type="SignalWorkflowExecutionRequest" required>
  Contains execution identifier, signal name, and input
</ParamField>

<ResponseField name="response" type="SignalWorkflowExecutionResponse">
  Empty response on success
</ResponseField>

#### SignalWithStartWorkflowExecution

Signals a workflow or starts it if it doesn't exist.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="signal_with_start_request" type="SignalWithStartWorkflowExecutionRequest" required>
  Combined signal and start parameters
</ParamField>

<ResponseField name="run_id" type="string">
  Run ID of the signaled or started workflow
</ResponseField>

#### QueryWorkflow

Executes a query against a workflow execution.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="request" type="QueryWorkflowRequest" required>
  Contains execution identifier and query details
</ParamField>

<ResponseField name="query_result" type="Payloads">
  Result of the query
</ResponseField>

<ResponseField name="query_rejected" type="QueryRejected">
  Query rejection details if rejected
</ResponseField>

#### RemoveSignalMutableState

Removes a signal from the mutable state.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ParamField path="request_id" type="string" required>
  Request ID of the signal to remove
</ParamField>

### Workflow Updates

#### UpdateWorkflowExecution

Executes an update on a workflow execution.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="update_request" type="UpdateWorkflowExecutionRequest" required>
  Update request with update name and arguments
</ParamField>

<ResponseField name="update_ref" type="UpdateRef">
  Reference to the update for polling
</ResponseField>

<ResponseField name="outcome" type="Outcome">
  Update outcome if completed synchronously
</ResponseField>

#### PollWorkflowExecutionUpdate

Polls for the result of a workflow update.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="update_ref" type="UpdateRef" required>
  Reference to the update
</ParamField>

<ResponseField name="outcome" type="Outcome">
  Update outcome (success or failure)
</ResponseField>

### History Operations

#### GetWorkflowExecutionHistory

Retrieves workflow execution history.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="request" type="GetWorkflowExecutionHistoryRequest" required>
  Contains execution identifier and pagination parameters
</ParamField>

<ResponseField name="history" type="History">
  History events
</ResponseField>

<ResponseField name="next_page_token" type="bytes">
  Token for next page
</ResponseField>

<ResponseField name="archived" type="bool">
  Whether history is from archive
</ResponseField>

#### GetWorkflowExecutionHistoryReverse

Retrieves workflow history in reverse order.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="request" type="GetWorkflowExecutionHistoryReverseRequest" required>
  Request parameters
</ParamField>

<ResponseField name="history" type="History">
  History events in reverse order
</ResponseField>

<ResponseField name="next_page_token" type="bytes">
  Token for next page
</ResponseField>

#### GetWorkflowExecutionRawHistoryV2

Retrieves raw history events as encoded blobs.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="request" type="GetWorkflowExecutionRawHistoryV2Request" required>
  Request with pagination parameters
</ParamField>

<ResponseField name="history_batches" type="DataBlob[]">
  Raw history batches
</ResponseField>

<ResponseField name="next_page_token" type="bytes">
  Pagination token
</ResponseField>

### Replication

#### ReplicateEventsV2

Replicates history events from another cluster.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Target workflow execution
</ParamField>

<ParamField path="events" type="VersionHistoryItem[]" required>
  Events to replicate
</ParamField>

<ResponseField name="response" type="ReplicateEventsV2Response">
  Empty response on success
</ResponseField>

#### ReplicateWorkflowState

Replicates complete workflow state.

<ParamField path="workflow_state" type="WorkflowState" required>
  Complete workflow state to replicate
</ParamField>

<ResponseField name="response" type="ReplicateWorkflowStateResponse">
  Empty response on success
</ResponseField>

#### GetReplicationMessages

Retrieves replication messages for a shard.

<ParamField path="tokens" type="ReplicationToken[]" required>
  Tokens indicating last received messages
</ParamField>

<ParamField path="cluster_name" type="string" required>
  Source cluster name
</ParamField>

<ResponseField name="replication_tasks" type="ReplicationTask[]">
  Batch of replication tasks
</ResponseField>

### Child Workflow Management

#### RecordChildExecutionCompleted

Records completion of a child workflow.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID of parent workflow
</ParamField>

<ParamField path="parent_execution" type="WorkflowExecution" required>
  Parent workflow execution
</ParamField>

<ParamField path="parent_initiated_id" type="int64" required>
  Event ID when child was initiated
</ParamField>

<ParamField path="completion_event" type="HistoryEvent" required>
  Child completion event
</ParamField>

### Additional Operations

#### ScheduleWorkflowTask

Schedules a new workflow task.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ParamField path="is_first_workflow_task" type="bool">
  Whether this is the first task
</ParamField>

#### ResetStickyTaskQueue

Resets the sticky task queue for a workflow.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ResponseField name="response" type="ResetStickyTaskQueueResponse">
  Empty response on success
</ResponseField>

#### RequestCancelWorkflowExecution

Requests cancellation of a workflow execution.

<ParamField path="namespace_id" type="string" required>
  Namespace UUID
</ParamField>

<ParamField path="cancel_request" type="RequestCancelWorkflowExecutionRequest" required>
  Cancellation request details
</ParamField>

<ResponseField name="response" type="RequestCancelWorkflowExecutionResponse">
  Empty response on success
</ResponseField>

## 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

* [Admin Service API](/api/admin-service)
* [Matching Service API](/api/matching-service)
* [Server Configuration](/reference/server-config)