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

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

<ParamField path="namespace" type="string" required>
  The namespace of the workflow execution
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  The workflow execution identifier containing workflow\_id and run\_id
</ParamField>

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

#### DescribeMutableState

Retrieves detailed information about the mutable state of a workflow execution.

<ParamField path="namespace" type="string" required>
  The namespace of the workflow execution
</ParamField>

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

<ResponseField name="cache_mutable_state_info" type="string">
  Cached mutable state information in JSON format
</ResponseField>

<ResponseField name="database_mutable_state" type="object">
  Current mutable state from the database
</ResponseField>

#### ImportWorkflowExecution

Imports a workflow execution from external source.

<ParamField path="namespace" type="string" required>
  Target namespace for the imported workflow
</ParamField>

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

<ParamField path="history_batches" type="DataBlob[]" required>
  History event batches to import
</ParamField>

#### DeleteWorkflowExecution

Permanently deletes a workflow execution and all its data.

<ParamField path="namespace" type="string" required>
  The namespace of the workflow
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  The workflow execution to delete
</ParamField>

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

### Shard Management

#### GetShard

Retrieves information about a specific history shard.

<ParamField path="shard_id" type="int32" required>
  The ID of the shard to retrieve
</ParamField>

<ResponseField name="shard_info" type="ShardInfo">
  Detailed information about the shard including range\_id, owner, and state
</ResponseField>

#### CloseShard

Closes a shard, releasing its ownership.

<ParamField path="shard_id" type="int32" required>
  The ID of the shard to close
</ParamField>

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

#### ListHistoryTasks

Lists tasks for a specific shard and category.

<ParamField path="shard_id" type="int32" required>
  The shard ID to list tasks from
</ParamField>

<ParamField path="category" type="TaskCategory" required>
  Task category (transfer, timer, replication, visibility)
</ParamField>

<ParamField path="task_range" type="TaskRange">
  Optional range to filter tasks
</ParamField>

<ResponseField name="tasks" type="Task[]">
  List of tasks matching the criteria
</ResponseField>

#### RemoveTask

Removes a specific task from a shard.

<ParamField path="shard_id" type="int32" required>
  The shard ID containing the task
</ParamField>

<ParamField path="category" type="TaskCategory" required>
  The task category
</ParamField>

<ParamField path="task_id" type="int64" required>
  The task ID to remove
</ParamField>

### Cluster Management

#### DescribeCluster

Returns detailed information about the Temporal cluster.

<ResponseField name="cluster_name" type="string">
  Name of the cluster
</ResponseField>

<ResponseField name="history_shard_count" type="int32">
  Total number of history shards
</ResponseField>

<ResponseField name="cluster_id" type="string">
  Unique cluster identifier
</ResponseField>

<ResponseField name="version_info" type="VersionInfo">
  Server version information
</ResponseField>

#### ListClusters

Lists all configured clusters including remote clusters.

<ParamField path="page_size" type="int32">
  Maximum number of results per page
</ParamField>

<ParamField path="next_page_token" type="bytes">
  Token for pagination
</ParamField>

<ResponseField name="clusters" type="ClusterInfo[]">
  List of cluster information
</ResponseField>

#### ListClusterMembers

Lists all members of the cluster by role.

<ParamField path="role" type="ServiceRole">
  Optional filter by service role (frontend, history, matching, worker)
</ParamField>

<ParamField path="page_size" type="int32">
  Maximum number of results per page
</ParamField>

<ResponseField name="members" type="ClusterMember[]">
  List of cluster members with their roles and addresses
</ResponseField>

#### AddOrUpdateRemoteCluster

Adds or updates a remote cluster configuration for cross-cluster replication.

<ParamField path="frontend_address" type="string" required>
  Frontend address of the remote cluster
</ParamField>

<ParamField path="enable_remote_cluster_connection" type="bool">
  Whether to enable connection to the remote cluster
</ParamField>

#### RemoveRemoteCluster

Removes a remote cluster configuration.

<ParamField path="cluster_name" type="string" required>
  Name of the remote cluster to remove
</ParamField>

### Replication Management

#### GetReplicationMessages

Retrieves replication messages for cross-cluster replication.

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

<ParamField path="last_retrieved_message_id" type="int64">
  Last received message ID for pagination
</ParamField>

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

#### GetNamespaceReplicationMessages

Retrieves namespace replication messages.

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

<ParamField path="last_retrieved_message_id" type="int64">
  Last message ID
</ParamField>

<ResponseField name="messages" type="ReplicationTask[]">
  Namespace replication tasks
</ResponseField>

#### StreamWorkflowReplicationMessages

Streams workflow replication messages (bidirectional streaming).

<ParamField path="sync_replication_state" type="SyncReplicationState">
  Replication synchronization state
</ParamField>

<ResponseField name="messages" type="WorkflowReplicationMessages" streaming>
  Stream of replication messages
</ResponseField>

#### ResendReplicationTasks

Resends replication tasks for a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

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

<ParamField path="start_event_id" type="int64">
  Starting event ID for resending
</ParamField>

<ParamField path="end_event_id" type="int64">
  Ending event ID
</ParamField>

### DLQ Operations

#### GetDLQMessages

Retrieves messages from a dead letter queue.

<ParamField path="type" type="DLQType" required>
  Type of DLQ (replication or namespace)
</ParamField>

<ParamField path="source_cluster" type="string">
  Source cluster for replication DLQ
</ParamField>

<ParamField path="shard_id" type="int32">
  Shard ID for shard-specific DLQ
</ParamField>

<ParamField path="maximum_page_size" type="int32">
  Maximum messages to return
</ParamField>

<ResponseField name="dlq_messages" type="DLQMessage[]">
  DLQ messages
</ResponseField>

#### PurgeDLQMessages

Purges messages from a DLQ up to a specific message ID.

<ParamField path="type" type="DLQType" required>
  Type of DLQ
</ParamField>

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

<ParamField path="inclusive_end_message_id" type="int64" required>
  Purge up to and including this message ID
</ParamField>

#### MergeDLQMessages

Merges DLQ messages back into the main queue.

<ParamField path="type" type="DLQType" required>
  Type of DLQ
</ParamField>

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

<ParamField path="inclusive_end_message_id" type="int64" required>
  Merge up to this message ID
</ParamField>

#### GetDLQTasks

Retrieves tasks from the DLQ with pagination.

<ParamField path="dlq_key" type="DLQKey" required>
  DLQ identifier containing queue type and source cluster
</ParamField>

<ParamField path="page_size" type="int32">
  Number of tasks to retrieve
</ParamField>

<ParamField path="next_page_token" type="bytes">
  Pagination token
</ParamField>

#### PurgeDLQTasks

Purges tasks from the DLQ.

<ParamField path="dlq_key" type="DLQKey" required>
  DLQ identifier
</ParamField>

<ParamField path="inclusive_max_task_metadata" type="TaskMetadata" required>
  Purge up to this task
</ParamField>

#### MergeDLQTasks

Merges DLQ tasks back into processing.

<ParamField path="dlq_key" type="DLQKey" required>
  DLQ identifier
</ParamField>

<ParamField path="inclusive_max_task_metadata" type="TaskMetadata" required>
  Merge up to this task
</ParamField>

### Search Attributes

#### AddSearchAttributes

Adds new custom search attributes to the cluster.

<ParamField path="search_attributes" type="map<string, SearchAttributeType>" required>
  Map of attribute names to types (Text, Keyword, Int, Double, Bool, Datetime, KeywordList)
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace for the search attributes
</ParamField>

#### RemoveSearchAttributes

Removes custom search attributes from a namespace.

<ParamField path="search_attributes" type="string[]" required>
  Names of search attributes to remove
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace containing the attributes
</ParamField>

#### GetSearchAttributes

Retrieves all search attributes for a namespace.

<ParamField path="namespace" type="string" required>
  Namespace to query
</ParamField>

<ResponseField name="custom_attributes" type="map<string, SearchAttributeType>">
  Custom search attributes
</ResponseField>

<ResponseField name="system_attributes" type="map<string, SearchAttributeType>">
  System-defined search attributes
</ResponseField>

### History Operations

#### GetWorkflowExecutionRawHistoryV2

Retrieves raw history events for a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

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

<ParamField path="start_event_id" type="int64">
  Starting event ID (default: 1)
</ParamField>

<ParamField path="end_event_id" type="int64">
  Ending event ID
</ParamField>

<ParamField path="maximum_page_size" type="int32">
  Maximum events per page
</ParamField>

<ParamField path="next_page_token" type="bytes">
  Token for pagination
</ParamField>

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

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

#### ReapplyEvents

Reapplies specific events to a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

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

<ParamField path="events" type="DataBlob" required>
  Events to reapply
</ParamField>

### Task Queue Operations

#### GetTaskQueueTasks

Retrieves tasks from a task queue.

<ParamField path="namespace" type="string" required>
  Namespace of the task queue
</ParamField>

<ParamField path="task_queue" type="string" required>
  Task queue name
</ParamField>

<ParamField path="task_queue_type" type="TaskQueueType" required>
  Type (workflow or activity)
</ParamField>

<ParamField path="max_tasks" type="int32">
  Maximum tasks to retrieve
</ParamField>

<ResponseField name="tasks" type="TaskQueueTask[]">
  List of task queue tasks
</ResponseField>

#### RefreshWorkflowTasks

Refreshes workflow tasks for an execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

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

### Health and Diagnostics

#### DescribeHistoryHost

Returns information about a history service host.

<ParamField path="host_address" type="string">
  Optional host address filter
</ParamField>

<ParamField path="shard_id" type="int32">
  Optional shard ID filter
</ParamField>

<ResponseField name="shards_count" type="int32">
  Number of shards on the host
</ResponseField>

<ResponseField name="address" type="string">
  Host address
</ResponseField>

#### DeepHealthCheck

Performs a deep health check of all subsystems.

<ResponseField name="state" type="HealthState">
  Overall health state (serving, not\_serving)
</ResponseField>

<ResponseField name="message" type="string">
  Health status message
</ResponseField>

### Additional Operations

#### ListQueues

Lists all queues in the system.

<ParamField path="queue_type" type="int32" required>
  Type of queue to list
</ParamField>

<ParamField path="page_size" type="int32">
  Maximum queues per page
</ParamField>

<ResponseField name="queues" type="QueueInfo[]">
  List of queues
</ResponseField>

#### AddTasks

Adds tasks to a queue.

<ParamField path="shard_id" type="int32" required>
  Target shard ID
</ParamField>

<ParamField path="tasks" type="Task[]" required>
  Tasks to add
</ParamField>

## 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](/api/history-service)
* [Server Configuration Reference](/reference/server-config)
* [Dynamic Config Reference](/reference/dynamic-config)