Skip to main content
The Frontend Service provides the public-facing gRPC API for Temporal clients, SDKs, and CLI tools. It handles authentication, authorization, rate limiting, and request routing to internal services.

​
Overview

The Frontend Service is the primary entry point for:
  • Workflow lifecycle operations (start, signal, query, terminate)
  • Activity execution management
  • Namespace management
  • Task queue operations
  • Workflow history queries
  • Search and visibility operations
  • Schedule management
  • Batch operations
This service is defined by the Temporal API proto definitions in the temporal.api.workflowservice.v1 package.

​
Service Architecture

The Frontend Service:
  • Accepts requests from Temporal SDKs and CLI
  • Performs authentication and authorization checks
  • Applies rate limiting policies
  • Routes requests to History, Matching, and Worker services
  • Handles datacenter redirection for global namespaces
  • Provides both gRPC and HTTP/gRPC-Web endpoints

​
Core Operations

​
Workflow Execution

​
StartWorkflowExecution

Starts a new workflow execution.
​
namespace
string
required
Namespace to start the workflow in
​
workflow_id
string
required
Unique identifier for the workflow (client-specified)
​
workflow_type
WorkflowType
required
Type of workflow to execute
​
task_queue
TaskQueue
required
Task queue for workflow tasks
​
input
Payloads
Input arguments for the workflow
​
workflow_execution_timeout
Duration
Maximum execution time for the workflow
​
workflow_run_timeout
Duration
Maximum run time for a single workflow run
​
workflow_task_timeout
Duration
Timeout for workflow task processing
​
workflow_id_reuse_policy
WorkflowIdReusePolicy
Policy for reusing workflow IDs
​
retry_policy
RetryPolicy
Retry policy for the workflow
​
cron_schedule
string
Cron schedule for recurring workflows
​
memo
Memo
Memo data attached to the workflow
​
search_attributes
SearchAttributes
Custom search attributes
​
run_id
string
Unique identifier for the workflow run

​
GetWorkflowExecutionHistory

Retrieves the history of a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
execution
WorkflowExecution
required
Workflow execution identifier (workflow_id and run_id)
​
maximum_page_size
int32
Maximum events per page
​
next_page_token
bytes
Pagination token
​
wait_new_event
bool
Long poll for new events
​
history_event_filter_type
HistoryEventFilterType
Filter for history events
​
history
History
Workflow history events
​
next_page_token
bytes
Token for next page
​
archived
bool
Whether history is from archival storage

​
DescribeWorkflowExecution

Retrieves detailed information about a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
execution
WorkflowExecution
required
Workflow execution identifier
​
execution_config
WorkflowExecutionConfig
Workflow configuration
​
workflow_execution_info
WorkflowExecutionInfo
Execution state and metadata
​
pending_activities
PendingActivityInfo[]
Currently pending activities
​
pending_children
PendingChildExecutionInfo[]
Pending child workflow executions

​
Workflow Control

​
SignalWorkflowExecution

Sends a signal to a running workflow.
​
namespace
string
required
Namespace of the workflow
​
workflow_execution
WorkflowExecution
required
Target workflow execution
​
signal_name
string
required
Name of the signal
​
input
Payloads
Signal input data
​
identity
string
required
Identity of the signal sender
​
request_id
string
Unique request ID for idempotency

​
QueryWorkflow

Queries the state of a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
execution
WorkflowExecution
required
Workflow execution to query
​
query
WorkflowQuery
required
Query definition with name and arguments
​
query_reject_condition
QueryRejectCondition
Conditions under which query should be rejected
​
query_result
Payloads
Result of the query
​
query_rejected
QueryRejected
Query rejection details if rejected

​
UpdateWorkflowExecution

Sends an update to a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
workflow_execution
WorkflowExecution
required
Target workflow execution
​
request
Request
required
Update request with name and arguments
​
wait_policy
WaitPolicy
Policy for waiting for update completion
​
outcome
Outcome
Update outcome if completed
​
update_ref
UpdateRef
Reference for polling update status

​
TerminateWorkflowExecution

Terminates a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
workflow_execution
WorkflowExecution
required
Workflow to terminate
​
reason
string
required
Reason for termination
​
details
Payloads
Additional termination details
​
identity
string
required
Identity of the terminator

​
CancelWorkflowExecution

Requests cancellation of a workflow execution.
​
namespace
string
required
Namespace of the workflow
​
workflow_execution
WorkflowExecution
required
Workflow to cancel
​
identity
string
required
Identity of the requester
​
request_id
string
Unique request ID

​
ResetWorkflowExecution

Resets a workflow execution to a previous state.
​
namespace
string
required
Namespace of the workflow
​
workflow_execution
WorkflowExecution
required
Workflow to reset
​
reason
string
required
Reason for reset
​
workflow_task_finish_event_id
int64
Event ID to reset to
​
request_id
string
Unique request ID
​
run_id
string
New run ID after reset

​
Task Operations

​
PollWorkflowTaskQueue

Polls for a workflow task.
​
namespace
string
required
Namespace to poll from
​
task_queue
TaskQueue
required
Task queue to poll
​
identity
string
required
Worker identity
​
binary_checksum
string
Worker binary checksum
​
task_token
bytes
Opaque task token
​
workflow_execution
WorkflowExecution
Workflow execution information
​
workflow_type
WorkflowType
Workflow type
​
history
History
History events for processing

​
RespondWorkflowTaskCompleted

Completes a workflow task with commands.
​
task_token
bytes
required
Task token from poll response
​
commands
Command[]
Workflow commands to execute
​
identity
string
required
Worker identity
​
sticky_attributes
StickyExecutionAttributes
Sticky task queue attributes
​
return_new_workflow_task
bool
Whether to return a new task immediately
​
messages
Message[]
Protocol messages
​
workflow_task
PollWorkflowTaskQueueResponse
New workflow task if requested

​
PollActivityTaskQueue

Polls for an activity task.
​
namespace
string
required
Namespace to poll from
​
task_queue
TaskQueue
required
Task queue to poll
​
identity
string
required
Worker identity
​
task_token
bytes
Task token
​
workflow_execution
WorkflowExecution
Parent workflow
​
activity_id
string
Activity identifier
​
activity_type
ActivityType
Activity type
​
input
Payloads
Activity input

​
RecordActivityTaskHeartbeat

Records a heartbeat for a long-running activity.
​
task_token
bytes
required
Activity task token
​
details
Payloads
Progress details
​
identity
string
required
Worker identity
​
cancel_requested
bool
Whether cancellation has been requested

​
RespondActivityTaskCompleted

Completes an activity task with a result.
​
task_token
bytes
required
Activity task token
​
result
Payloads
Activity result
​
identity
string
required
Worker identity

​
RespondActivityTaskFailed

Marks an activity task as failed.
​
task_token
bytes
required
Activity task token
​
failure
Failure
Failure details
​
identity
string
required
Worker identity

​
Namespace Operations

​
RegisterNamespace

Registers a new namespace.
​
namespace
string
required
Namespace name
​
description
string
Namespace description
​
owner_email
string
Owner email address
​
workflow_execution_retention_period
Duration
required
Retention period for closed workflows
​
clusters
ClusterReplicationConfig[]
Cluster replication configuration
​
data
map<string, string>
Custom namespace data

​
DescribeNamespace

Retrieves namespace information.
​
namespace
string
required
Namespace name
​
namespace_info
NamespaceInfo
Namespace metadata
​
config
NamespaceConfig
Namespace configuration
​
replication_config
NamespaceReplicationConfig
Replication settings

​
UpdateNamespace

Updates namespace configuration.
​
namespace
string
required
Namespace to update
​
update_info
UpdateNamespaceInfo
Updated namespace metadata
​
config
NamespaceConfig
Updated configuration
​
replication_config
NamespaceReplicationConfig
Updated replication settings

​
ListNamespaces

Lists all namespaces.
​
page_size
int32
Maximum namespaces per page
​
next_page_token
bytes
Pagination token
​
namespaces
DescribeNamespaceResponse[]
List of namespaces
​
next_page_token
bytes
Token for next page

​
ListWorkflowExecutions

Lists workflow executions with optional filtering.
​
namespace
string
required
Namespace to search
​
page_size
int32
Maximum executions per page
​
next_page_token
bytes
Pagination token
​
query
string
SQL-like search query
​
executions
WorkflowExecutionInfo[]
List of workflow executions
​
next_page_token
bytes
Token for next page

​
ScanWorkflowExecutions

Scans workflow executions (similar to List but with different consistency guarantees).
​
namespace
string
required
Namespace to scan
​
page_size
int32
Maximum executions per page
​
next_page_token
bytes
Pagination token
​
query
string
Search query
​
executions
WorkflowExecutionInfo[]
List of workflow executions

​
CountWorkflowExecutions

Counts workflow executions matching a query.
​
namespace
string
required
Namespace to count in
​
query
string
Search query
​
count
int64
Number of matching executions

​
Task Queue Management

​
DescribeTaskQueue

Retrieves information about a task queue.
​
namespace
string
required
Namespace of the task queue
​
task_queue
TaskQueue
required
Task queue to describe
​
task_queue_type
TaskQueueType
Type of task queue (workflow or activity)
​
include_task_queue_status
bool
Whether to include status information
​
pollers
PollerInfo[]
Active pollers
​
task_queue_status
TaskQueueStatus
Task queue status

​
Configuration

Frontend Service configuration is defined in the server config file: 
services:
  frontend:
    rpc:
      grpcPort: 7233
      httpPort: 7243
      membershipPort: 6933
      bindOnIP: "0.0.0.0"

​
Authentication & Authorization

The Frontend Service supports:
  • JWT-based authentication
  • Custom authorizers via plugin
  • Claim mappers for extracting permissions
  • Per-namespace access control

​
Rate Limiting

Rate limiting is applied per:
  • API method
  • Namespace
  • User identity
Configure via dynamic config keys.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us