Frontend Service API

Public-facing Temporal Server API for client operations

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

Visibility and Search

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

• History Service API
• Matching Service API
• Server Configuration
• Authentication Guide