Skip to main content
The Admin Service provides low-level administrative operations for managing Temporal Server infrastructure. This service is intended for operational debugging and maintenance tasks.

​
Overview

The Admin Service is an internal gRPC service that exposes administrative endpoints for:
  • Workflow execution management and debugging
  • Shard management and operations
  • Cluster administration and remote cluster management
  • Dead letter queue (DLQ) operations
  • Search attributes management
  • Replication task management
  • Task queue administration

​
Service Methods

​
Workflow State Management

​
RebuildMutableState

Rebuilds the mutable state of a workflow execution from history events.
​
namespace
string
required
The namespace of the workflow execution
​
execution
WorkflowExecution
required
The workflow execution identifier containing workflow_id and run_id
​
response
RebuildMutableStateResponse
Empty response on success

​
DescribeMutableState

Retrieves detailed information about the mutable state of a workflow execution.
​
namespace
string
required
The namespace of the workflow execution
​
execution
WorkflowExecution
required
The workflow execution identifier
​
cache_mutable_state_info
string
Cached mutable state information in JSON format
​
database_mutable_state
object
Current mutable state from the database

​
ImportWorkflowExecution

Imports a workflow execution from external source.
​
namespace
string
required
Target namespace for the imported workflow
​
execution
WorkflowExecution
required
Workflow execution details
​
history_batches
DataBlob[]
required
History event batches to import

​
DeleteWorkflowExecution

Permanently deletes a workflow execution and all its data.
​
namespace
string
required
The namespace of the workflow
​
execution
WorkflowExecution
required
The workflow execution to delete
​
response
DeleteWorkflowExecutionResponse
Empty response on successful deletion

​
Shard Management

​
GetShard

Retrieves information about a specific history shard.
​
shard_id
int32
required
The ID of the shard to retrieve
​
shard_info
ShardInfo
Detailed information about the shard including range_id, owner, and state

​
CloseShard

Closes a shard, releasing its ownership.
​
shard_id
int32
required
The ID of the shard to close
​
response
CloseShardResponse
Empty response on success

​
ListHistoryTasks

Lists tasks for a specific shard and category.
​
shard_id
int32
required
The shard ID to list tasks from
​
category
TaskCategory
required
Task category (transfer, timer, replication, visibility)
​
task_range
TaskRange
Optional range to filter tasks
​
tasks
Task[]
List of tasks matching the criteria

​
RemoveTask

Removes a specific task from a shard.
​
shard_id
int32
required
The shard ID containing the task
​
category
TaskCategory
required
The task category
​
task_id
int64
required
The task ID to remove

​
Cluster Management

​
DescribeCluster

Returns detailed information about the Temporal cluster.
​
cluster_name
string
Name of the cluster
​
history_shard_count
int32
Total number of history shards
​
cluster_id
string
Unique cluster identifier
​
version_info
VersionInfo
Server version information

​
ListClusters

Lists all configured clusters including remote clusters.
​
page_size
int32
Maximum number of results per page
​
next_page_token
bytes
Token for pagination
​
clusters
ClusterInfo[]
List of cluster information

​
ListClusterMembers

Lists all members of the cluster by role.
​
role
ServiceRole
Optional filter by service role (frontend, history, matching, worker)
​
page_size
int32
Maximum number of results per page
​
members
ClusterMember[]
List of cluster members with their roles and addresses

​
AddOrUpdateRemoteCluster

Adds or updates a remote cluster configuration for cross-cluster replication.
​
frontend_address
string
required
Frontend address of the remote cluster
​
enable_remote_cluster_connection
bool
Whether to enable connection to the remote cluster

​
RemoveRemoteCluster

Removes a remote cluster configuration.
​
cluster_name
string
required
Name of the remote cluster to remove

​
Replication Management

​
GetReplicationMessages

Retrieves replication messages for cross-cluster replication.
​
cluster_name
string
required
Target cluster name
​
last_retrieved_message_id
int64
Last received message ID for pagination
​
replication_tasks
ReplicationTask[]
Batch of replication tasks

​
GetNamespaceReplicationMessages

Retrieves namespace replication messages.
​
cluster_name
string
required
Target cluster name
​
last_retrieved_message_id
int64
Last message ID
​
messages
ReplicationTask[]
Namespace replication tasks

​
StreamWorkflowReplicationMessages

Streams workflow replication messages (bidirectional streaming).
​
sync_replication_state
SyncReplicationState
Replication synchronization state
​
messages
WorkflowReplicationMessages
Stream of replication messages

​
ResendReplicationTasks

Resends replication tasks for a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
execution
WorkflowExecution
required
Workflow execution identifier
​
start_event_id
int64
Starting event ID for resending
​
end_event_id
int64
Ending event ID

​
DLQ Operations

​
GetDLQMessages

Retrieves messages from a dead letter queue.
​
type
DLQType
required
Type of DLQ (replication or namespace)
​
source_cluster
string
Source cluster for replication DLQ
​
shard_id
int32
Shard ID for shard-specific DLQ
​
maximum_page_size
int32
Maximum messages to return
​
dlq_messages
DLQMessage[]
DLQ messages

​
PurgeDLQMessages

Purges messages from a DLQ up to a specific message ID.
​
type
DLQType
required
Type of DLQ
​
source_cluster
string
Source cluster name
​
inclusive_end_message_id
int64
required
Purge up to and including this message ID

​
MergeDLQMessages

Merges DLQ messages back into the main queue.
​
type
DLQType
required
Type of DLQ
​
source_cluster
string
Source cluster name
​
inclusive_end_message_id
int64
required
Merge up to this message ID

​
GetDLQTasks

Retrieves tasks from the DLQ with pagination.
​
dlq_key
DLQKey
required
DLQ identifier containing queue type and source cluster
​
page_size
int32
Number of tasks to retrieve
​
next_page_token
bytes
Pagination token

​
PurgeDLQTasks

Purges tasks from the DLQ.
​
dlq_key
DLQKey
required
DLQ identifier
​
inclusive_max_task_metadata
TaskMetadata
required
Purge up to this task

​
MergeDLQTasks

Merges DLQ tasks back into processing.
​
dlq_key
DLQKey
required
DLQ identifier
​
inclusive_max_task_metadata
TaskMetadata
required
Merge up to this task

​
Search Attributes

​
AddSearchAttributes

Adds new custom search attributes to the cluster.
​
search_attributes
map<string, SearchAttributeType>
required
Map of attribute names to types (Text, Keyword, Int, Double, Bool, Datetime, KeywordList)
​
namespace
string
required
Namespace for the search attributes

​
RemoveSearchAttributes

Removes custom search attributes from a namespace.
​
search_attributes
string[]
required
Names of search attributes to remove
​
namespace
string
required
Namespace containing the attributes

​
GetSearchAttributes

Retrieves all search attributes for a namespace.
​
namespace
string
required
Namespace to query
​
custom_attributes
map<string, SearchAttributeType>
Custom search attributes
​
system_attributes
map<string, SearchAttributeType>
System-defined search attributes

​
History Operations

​
GetWorkflowExecutionRawHistoryV2

Retrieves raw history events for a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
execution
WorkflowExecution
required
Workflow execution identifier
​
start_event_id
int64
Starting event ID (default: 1)
​
end_event_id
int64
Ending event ID
​
maximum_page_size
int32
Maximum events per page
​
next_page_token
bytes
Token for pagination
​
history_batches
DataBlob[]
Raw history event batches
​
next_page_token
bytes
Token for next page

​
ReapplyEvents

Reapplies specific events to a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
execution
WorkflowExecution
required
Workflow execution identifier
​
events
DataBlob
required
Events to reapply

​
Task Queue Operations

​
GetTaskQueueTasks

Retrieves tasks from a task queue.
​
namespace
string
required
Namespace of the task queue
​
task_queue
string
required
Task queue name
​
task_queue_type
TaskQueueType
required
Type (workflow or activity)
​
max_tasks
int32
Maximum tasks to retrieve
​
tasks
TaskQueueTask[]
List of task queue tasks

​
RefreshWorkflowTasks

Refreshes workflow tasks for an execution.
​
namespace
string
required
Namespace of the workflow
​
execution
WorkflowExecution
required
Workflow execution identifier

​
Health and Diagnostics

​
DescribeHistoryHost

Returns information about a history service host.
​
host_address
string
Optional host address filter
​
shard_id
int32
Optional shard ID filter
​
shards_count
int32
Number of shards on the host
​
address
string
Host address

​
DeepHealthCheck

Performs a deep health check of all subsystems.
​
state
HealthState
Overall health state (serving, not_serving)
​
message
string
Health status message

​
Additional Operations

​
ListQueues

Lists all queues in the system.
​
queue_type
int32
required
Type of queue to list
​
page_size
int32
Maximum queues per page
​
queues
QueueInfo[]
List of queues

​
AddTasks

Adds tasks to a queue.
​
shard_id
int32
required
Target shard ID
​
tasks
Task[]
required
Tasks to add

​
Authentication

The Admin Service requires proper authentication and authorization. Ensure your client has admin-level permissions to access these endpoints.

​
Usage Notes

  • Most Admin Service operations are low-level and should be used with caution in production
  • Some operations like DeleteWorkflowExecution are destructive and cannot be undone
  • DLQ operations are critical for maintaining replication health
  • Always test admin operations in a development environment first
  • Monitor operation impact on cluster performance

​
Error Handling

Common error codes:
  • NOT_FOUND - Requested resource does not exist
  • INVALID_ARGUMENT - Invalid parameters provided
  • PERMISSION_DENIED - Insufficient permissions
  • INTERNAL - Internal server error
  • RESOURCE_EXHAUSTED - Rate limit exceeded

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us