Admin Service API

Internal administrative operations for Temporal Server

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

• History Service API
• Server Configuration Reference
• Dynamic Config Reference