Frontend Service API

Overview

The Frontend Service is the primary entry point for Cadence clients. It provides all public-facing APIs for workflow execution, domain management, and task coordination. Service Location: service/frontend/api/interface.go

Health Check

Health

Check the health status of the frontend service.

Health(context.Context) (*types.HealthStatus, error)

HealthStatus

object

Show properties

boolean

Whether the service is healthy

Msg

string

Health status message

Workflow Execution APIs

StartWorkflowExecution

Start a new workflow execution.

StartWorkflowExecution(context.Context, *types.StartWorkflowExecutionRequest) (*types.StartWorkflowExecutionResponse, error)

Domain

string

required

The domain name where the workflow will execute

WorkflowId

string

required

Unique identifier for the workflow execution

WorkflowType

required

The workflow type to execute

TaskList

required

Task list where decision tasks will be dispatched

Input

[]byte

Serialized input parameters for the workflow

ExecutionStartToCloseTimeoutSeconds

int32

required

Maximum time the workflow can run before timing out

TaskStartToCloseTimeoutSeconds

int32

required

Maximum time a decision task can run before timing out

Identity

string

Identity of the client starting the workflow

RequestId

string

Unique request identifier for idempotency

WorkflowIdReusePolicy

Policy for reusing workflow IDs (AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate)

RetryPolicy

Retry policy for automatic workflow retries

CronSchedule

string

Cron schedule for periodic workflow execution

Memo

Non-indexed metadata attached to the workflow

SearchAttributes

Indexed attributes for workflow search

Header

Context propagation headers

RunId

string

Unique identifier for this workflow execution run

Example Request:

{
  "domain": "my-domain",
  "workflowId": "my-workflow-123",
  "workflowType": { "name": "MyWorkflow" },
  "taskList": { "name": "my-task-list" },
  "executionStartToCloseTimeoutSeconds": 3600,
  "taskStartToCloseTimeoutSeconds": 10,
  "identity": "my-worker@host-1"
}

Error Cases:

BadRequestError: Invalid request parameters
WorkflowExecutionAlreadyStartedError: Workflow with same ID already running
DomainNotActiveError: Domain is not active
ServiceBusyError: Service is throttling requests

StartWorkflowExecutionAsync

Start a workflow execution asynchronously with lower latency.

StartWorkflowExecutionAsync(context.Context, *types.StartWorkflowExecutionAsyncRequest) (*types.StartWorkflowExecutionAsyncResponse, error)

Same parameters as StartWorkflowExecution but returns immediately without waiting for persistence.

SignalWorkflowExecution

Send a signal to a running workflow execution.

SignalWorkflowExecution(context.Context, *types.SignalWorkflowExecutionRequest) error

Domain

string

required

Domain name of the workflow

WorkflowExecution

required

Workflow ID and optional Run ID

SignalName

string

required

Name of the signal to send

Input

[]byte

Serialized signal payload

Identity

string

Identity of the client sending the signal

RequestId

string

Unique request identifier for idempotency

SignalWithStartWorkflowExecution

Signal a workflow execution, starting it if it doesn’t exist.

SignalWithStartWorkflowExecution(context.Context, *types.SignalWithStartWorkflowExecutionRequest) (*types.StartWorkflowExecutionResponse, error)

Combines parameters from both StartWorkflowExecution and SignalWorkflowExecution.

TerminateWorkflowExecution

Terminate a running workflow execution.

TerminateWorkflowExecution(context.Context, *types.TerminateWorkflowExecutionRequest) error

Domain

string

required

Domain name of the workflow

WorkflowExecution

required

Workflow ID and optional Run ID

Reason

string

Reason for termination

Details

[]byte

Additional termination details

Identity

string

Identity of the client terminating the workflow

RequestCancelWorkflowExecution

Request cancellation of a workflow execution.

RequestCancelWorkflowExecution(context.Context, *types.RequestCancelWorkflowExecutionRequest) error

Domain

string

required

Domain name of the workflow

WorkflowExecution

required

Workflow ID and optional Run ID

Identity

string

Identity of the client requesting cancellation

RequestId

string

Unique request identifier

ResetWorkflowExecution

Reset a workflow execution to a previous decision task.

ResetWorkflowExecution(context.Context, *types.ResetWorkflowExecutionRequest) (*types.ResetWorkflowExecutionResponse, error)

Domain

string

required

Domain name of the workflow

WorkflowExecution

required

Workflow ID and Run ID to reset

Reason

string

required

Reason for the reset

DecisionFinishEventId

int64

required

Event ID of the decision to reset to

RequestId

string

Unique request identifier

SkipSignalReapply

boolean

Whether to skip reapplying signals after reset

RestartWorkflowExecution

Restart a completed workflow execution.

RestartWorkflowExecution(context.Context, *types.RestartWorkflowExecutionRequest) (*types.RestartWorkflowExecutionResponse, error)

Workflow Query APIs

DescribeWorkflowExecution

Get detailed information about a workflow execution.

DescribeWorkflowExecution(context.Context, *types.DescribeWorkflowExecutionRequest) (*types.DescribeWorkflowExecutionResponse, error)

Domain

string

required

Domain name of the workflow

WorkflowExecution

required

Workflow ID and optional Run ID

ExecutionConfiguration

WorkflowExecutionConfiguration

Workflow configuration including timeouts and task list

WorkflowExecutionInfo

Current workflow execution state and metadata

PendingActivities

[]PendingActivityInfo

List of pending activity tasks

PendingChildren

[]PendingChildExecutionInfo

List of pending child workflows

PendingDecision

PendingDecisionInfo

Information about pending decision task

DiagnoseWorkflowExecution

Diagnose issues with a workflow execution.

DiagnoseWorkflowExecution(context.Context, *types.DiagnoseWorkflowExecutionRequest) (*types.DiagnoseWorkflowExecutionResponse, error)

GetWorkflowExecutionHistory

Retrieve the event history for a workflow execution.

GetWorkflowExecutionHistory(context.Context, *types.GetWorkflowExecutionHistoryRequest) (*types.GetWorkflowExecutionHistoryResponse, error)

Domain

string

required

Domain name of the workflow

WorkflowExecution

required

Workflow ID and optional Run ID

MaximumPageSize

int32

Maximum number of events to return (default: 100)

NextPageToken

[]byte

Token for pagination

WaitForNewEvent

boolean

Long poll for new events

HistoryEventFilterType

Filter type (AllEvent, CloseEvent)

SkipArchival

boolean

Skip reading from archival storage

History

List of history events

RawHistory

[]DataBlob

Raw event data in binary format

NextPageToken

[]byte

Token for next page of results

Archived

boolean

Whether history was retrieved from archival

QueryWorkflow

Query the state of a running workflow.

QueryWorkflow(context.Context, *types.QueryWorkflowRequest) (*types.QueryWorkflowResponse, error)

Domain

string

required

Domain name of the workflow

WorkflowExecution

required

Workflow ID and optional Run ID

Query

WorkflowQuery

required

Query definition including query type and arguments

QueryRejectCondition

Condition for rejecting the query

QueryConsistencyLevel

Consistency level for the query (Eventual, Strong)

QueryResult

[]byte

Serialized query result

QueryRejected

Information if query was rejected

Workflow List APIs

ListOpenWorkflowExecutions

List open workflow executions in a domain.

ListOpenWorkflowExecutions(context.Context, *types.ListOpenWorkflowExecutionsRequest) (*types.ListOpenWorkflowExecutionsResponse, error)

ListClosedWorkflowExecutions

List closed workflow executions in a domain.

ListClosedWorkflowExecutions(context.Context, *types.ListClosedWorkflowExecutionsRequest) (*types.ListClosedWorkflowExecutionsResponse, error)

ListWorkflowExecutions

List workflow executions using advanced visibility queries.

ListWorkflowExecutions(context.Context, *types.ListWorkflowExecutionsRequest) (*types.ListWorkflowExecutionsResponse, error)

Domain

string

required

Domain to query

PageSize

int32

Number of results per page

NextPageToken

[]byte

Pagination token

Query

string

SQL-like query string for filtering

ScanWorkflowExecutions

Scan all workflow executions (no specific ordering).

ScanWorkflowExecutions(context.Context, *types.ListWorkflowExecutionsRequest) (*types.ListWorkflowExecutionsResponse, error)

CountWorkflowExecutions

Count workflow executions matching a query.

CountWorkflowExecutions(context.Context, *types.CountWorkflowExecutionsRequest) (*types.CountWorkflowExecutionsResponse, error)

ListArchivedWorkflowExecutions

List workflow executions from archival storage.

ListArchivedWorkflowExecutions(context.Context, *types.ListArchivedWorkflowExecutionsRequest) (*types.ListArchivedWorkflowExecutionsResponse, error)

Task Polling APIs

PollForDecisionTask

Long poll for a decision task from a task list.

PollForDecisionTask(context.Context, *types.PollForDecisionTaskRequest) (*types.PollForDecisionTaskResponse, error)

Domain

string

required

Domain to poll from

TaskList

required

Task list to poll

Identity

string

Worker identity

BinaryChecksum

string

Worker binary checksum

PollForActivityTask

Long poll for an activity task from a task list.

PollForActivityTask(context.Context, *types.PollForActivityTaskRequest) (*types.PollForActivityTaskResponse, error)

Domain

string

required

Domain to poll from

TaskList

required

Task list to poll

Identity

string

Worker identity

TaskListMetadata

Task list metadata for routing

Task Completion APIs

RespondDecisionTaskCompleted

Respond to a decision task with decisions.

RespondDecisionTaskCompleted(context.Context, *types.RespondDecisionTaskCompletedRequest) (*types.RespondDecisionTaskCompletedResponse, error)

TaskToken

[]byte

required

Task token from poll response

Decisions

[]Decision

List of decisions to execute

ExecutionContext

[]byte

Execution context to persist

Identity

string

Worker identity

StickyAttributes

StickyExecutionAttributes

Sticky task list attributes

ReturnNewDecisionTask

boolean

Return a new decision task immediately

ForceCreateNewDecisionTask

boolean

Force creation of a new decision task

BinaryChecksum

string

Worker binary checksum

QueryResults

map[string]WorkflowQueryResult

Query results if queries were processed

RespondDecisionTaskFailed

Report a decision task failure.

RespondDecisionTaskFailed(context.Context, *types.RespondDecisionTaskFailedRequest) error

RespondActivityTaskCompleted

Complete an activity task successfully.

RespondActivityTaskCompleted(context.Context, *types.RespondActivityTaskCompletedRequest) error

RespondActivityTaskCompletedByID

Complete an activity task by activity ID.

RespondActivityTaskCompletedByID(context.Context, *types.RespondActivityTaskCompletedByIDRequest) error

RespondActivityTaskFailed

Report an activity task failure.

RespondActivityTaskFailed(context.Context, *types.RespondActivityTaskFailedRequest) error

RespondActivityTaskFailedByID

Report an activity task failure by activity ID.

RespondActivityTaskFailedByID(context.Context, *types.RespondActivityTaskFailedByIDRequest) error

RespondActivityTaskCanceled

Report an activity task cancellation.

RespondActivityTaskCanceled(context.Context, *types.RespondActivityTaskCanceledRequest) error

RespondActivityTaskCanceledByID

Report an activity task cancellation by activity ID.

RespondActivityTaskCanceledByID(context.Context, *types.RespondActivityTaskCanceledByIDRequest) error

RecordActivityTaskHeartbeat

Record a heartbeat for a long-running activity.

RecordActivityTaskHeartbeat(context.Context, *types.RecordActivityTaskHeartbeatRequest) (*types.RecordActivityTaskHeartbeatResponse, error)

TaskToken

[]byte

required

Task token from activity task

Details

[]byte

Progress details

Identity

string

Worker identity

CancelRequested

boolean

Whether the activity has been requested to cancel

RecordActivityTaskHeartbeatByID

Record heartbeat by activity ID.

RecordActivityTaskHeartbeatByID(context.Context, *types.RecordActivityTaskHeartbeatByIDRequest) (*types.RecordActivityTaskHeartbeatResponse, error)

RespondQueryTaskCompleted

Respond to a query task.

RespondQueryTaskCompleted(context.Context, *types.RespondQueryTaskCompletedRequest) error

Domain Management APIs

RegisterDomain

RegisterDomain(context.Context, *types.RegisterDomainRequest) error

Name

string

required

Domain name (unique)

Description

string

Domain description

OwnerEmail

string

required

Owner email address

WorkflowExecutionRetentionPeriodInDays

int32

required

Number of days to retain closed workflow data

EmitMetric

boolean

Whether to emit metrics for this domain

Clusters

[]ClusterReplicationConfiguration

Cluster replication configuration

ActiveClusterName

string

Name of the active cluster

Data

map[string]string

Key-value metadata

SecurityToken

string

Security token for authorization

IsGlobalDomain

boolean

Whether this is a global domain

HistoryArchivalStatus

ArchivalStatus

History archival status (Disabled/Enabled)

HistoryArchivalURI

string

URI for history archival

VisibilityArchivalStatus

ArchivalStatus

Visibility archival status

VisibilityArchivalURI

string

URI for visibility archival

DescribeDomain

Get domain information.

DescribeDomain(context.Context, *types.DescribeDomainRequest) (*types.DescribeDomainResponse, error)

Name

string

Domain name (either Name or UUID required)

UUID

string

Domain UUID (either Name or UUID required)

UpdateDomain

Update domain configuration.

UpdateDomain(context.Context, *types.UpdateDomainRequest) (*types.UpdateDomainResponse, error)

DeprecateDomain

Deprecate a domain (soft delete).

DeprecateDomain(context.Context, *types.DeprecateDomainRequest) error

DeleteDomain

Delete a domain permanently.

DeleteDomain(context.Context, *types.DeleteDomainRequest) error

ListDomains

List all domains.

ListDomains(context.Context, *types.ListDomainsRequest) (*types.ListDomainsResponse, error)

FailoverDomain

Failover a domain to another cluster.

FailoverDomain(context.Context, *types.FailoverDomainRequest) (*types.FailoverDomainResponse, error)

ListFailoverHistory

List domain failover history.

ListFailoverHistory(context.Context, *types.ListFailoverHistoryRequest) (*types.ListFailoverHistoryResponse, error)

Task List APIs

DescribeTaskList

Get information about a task list.

DescribeTaskList(context.Context, *types.DescribeTaskListRequest) (*types.DescribeTaskListResponse, error)

Domain

string

required

Domain name

TaskList

required

Task list to describe

TaskListType

required

Type (Decision or Activity)

IncludeTaskListStatus

boolean

Include detailed status information

ListTaskListPartitions

List partitions for a task list.

ListTaskListPartitions(context.Context, *types.ListTaskListPartitionsRequest) (*types.ListTaskListPartitionsResponse, error)

GetTaskListsByDomain

Get all task lists in a domain.

GetTaskListsByDomain(context.Context, *types.GetTaskListsByDomainRequest) (*types.GetTaskListsByDomainResponse, error)

RefreshWorkflowTasks

Refresh workflow tasks in a task list.

RefreshWorkflowTasks(context.Context, *types.RefreshWorkflowTasksRequest) error

ResetStickyTaskList

Reset sticky task list for a workflow.

ResetStickyTaskList(context.Context, *types.ResetStickyTaskListRequest) (*types.ResetStickyTaskListResponse, error)

Search & Metadata APIs

GetSearchAttributes

Get valid search attribute keys.

GetSearchAttributes(context.Context) (*types.GetSearchAttributesResponse, error)

Keys

map[string]IndexedValueType

Map of search attribute keys to their data types

GetClusterInfo

Get cluster information.

GetClusterInfo(context.Context) (*types.ClusterInfo, error)

SupportedClientVersions

Supported client version ranges

Error Reference

BadRequestError

Invalid request parameters.

type BadRequestError struct {
    Message string
}

EntityNotExistsError

Requested entity (workflow, domain, etc.) does not exist.

type EntityNotExistsError struct {
    Message        string
    CurrentCluster string
    ActiveCluster  string
}

WorkflowExecutionAlreadyStartedError

Workflow with the same ID is already running.

type WorkflowExecutionAlreadyStartedError struct {
    Message        string
    StartRequestID string
    RunID          string
}

DomainNotActiveError

Domain is not active in the current cluster.

type DomainNotActiveError struct {
    Message        string
    DomainName     string
    CurrentCluster string
    ActiveCluster  string
}

ServiceBusyError

Service is throttling requests due to high load.

type ServiceBusyError struct {
    Message string
}

QueryFailedError

Workflow query failed.

type QueryFailedError struct {
    Message string
}

Rate Limiting

The Frontend Service implements multi-level rate limiting:

Global RPS: frontend.rps (default: 1200)
Domain RPS: frontend.domainrps (default: 1000 per domain)
Visibility RPS: Separate limits for list/scan operations

Rate-limited requests return ServiceBusyError.

Best Practices

Idempotency

Always provide a RequestId for operations that modify state:

StartWorkflowExecution
SignalWorkflowExecution
RequestCancelWorkflowExecution

Cadence deduplicates requests within the retention period.

Long Polling

For PollForDecisionTask and PollForActivityTask:

Set appropriate context timeout (recommended: 60-90 seconds)
Handle EntityNotExistsError for shutdown scenarios
Use sticky task lists for decision tasks to reduce latency

Pagination

When listing workflows or history:

Use PageSize to control result count
Store and pass NextPageToken for subsequent requests
History can be large; consider using filters

Query Consistency

For QueryWorkflow:

Use QueryConsistencyLevel.Strong for critical reads
Use QueryConsistencyLevel.Eventual for dashboards (lower latency)

Service APIs

Data Types

​Overview

​Health Check

​Health

​Workflow Execution APIs

​StartWorkflowExecution

​StartWorkflowExecutionAsync

​SignalWorkflowExecution

​SignalWithStartWorkflowExecution

​TerminateWorkflowExecution

​RequestCancelWorkflowExecution

​ResetWorkflowExecution

​RestartWorkflowExecution

​Workflow Query APIs

​DescribeWorkflowExecution

​DiagnoseWorkflowExecution

​GetWorkflowExecutionHistory

​QueryWorkflow

​Workflow List APIs

​ListOpenWorkflowExecutions

​ListClosedWorkflowExecutions

​ListWorkflowExecutions

​ScanWorkflowExecutions

​CountWorkflowExecutions

​ListArchivedWorkflowExecutions

​Task Polling APIs

​PollForDecisionTask

​PollForActivityTask

​Task Completion APIs

​RespondDecisionTaskCompleted

​RespondDecisionTaskFailed

​RespondActivityTaskCompleted

​RespondActivityTaskCompletedByID

​RespondActivityTaskFailed

​RespondActivityTaskFailedByID

​RespondActivityTaskCanceled

​RespondActivityTaskCanceledByID

​RecordActivityTaskHeartbeat

​RecordActivityTaskHeartbeatByID

​RespondQueryTaskCompleted

​Domain Management APIs

​RegisterDomain

​DescribeDomain

​UpdateDomain

​DeprecateDomain

​DeleteDomain

​ListDomains

​FailoverDomain

​ListFailoverHistory

​Task List APIs

​DescribeTaskList

​ListTaskListPartitions

​GetTaskListsByDomain

​RefreshWorkflowTasks

​ResetStickyTaskList

​Search & Metadata APIs

​GetSearchAttributes

​GetClusterInfo

​Error Reference

​BadRequestError

​EntityNotExistsError

​WorkflowExecutionAlreadyStartedError

​DomainNotActiveError

​ServiceBusyError

​QueryFailedError

​Rate Limiting

​Best Practices

​Idempotency

​Long Polling

​Pagination

​Query Consistency

​See Also

Build docs developers (and LLMs) love

Overview

Health Check

Health

Workflow Execution APIs

StartWorkflowExecution

StartWorkflowExecutionAsync

SignalWorkflowExecution

SignalWithStartWorkflowExecution

TerminateWorkflowExecution

RequestCancelWorkflowExecution

ResetWorkflowExecution

RestartWorkflowExecution

Workflow Query APIs

DescribeWorkflowExecution

DiagnoseWorkflowExecution

GetWorkflowExecutionHistory

QueryWorkflow

Workflow List APIs

ListOpenWorkflowExecutions

ListClosedWorkflowExecutions

ListWorkflowExecutions

ScanWorkflowExecutions

CountWorkflowExecutions

ListArchivedWorkflowExecutions

Task Polling APIs

PollForDecisionTask

PollForActivityTask

Task Completion APIs

RespondDecisionTaskCompleted

RespondDecisionTaskFailed

RespondActivityTaskCompleted

RespondActivityTaskCompletedByID

RespondActivityTaskFailed

RespondActivityTaskFailedByID

RespondActivityTaskCanceled

RespondActivityTaskCanceledByID

RecordActivityTaskHeartbeat

RecordActivityTaskHeartbeatByID

RespondQueryTaskCompleted

Domain Management APIs

RegisterDomain

DescribeDomain

UpdateDomain

DeprecateDomain

DeleteDomain

ListDomains

FailoverDomain

ListFailoverHistory

Task List APIs

DescribeTaskList

ListTaskListPartitions

GetTaskListsByDomain

RefreshWorkflowTasks

ResetStickyTaskList

Search & Metadata APIs

GetSearchAttributes

GetClusterInfo

Error Reference

BadRequestError

EntityNotExistsError

WorkflowExecutionAlreadyStartedError

DomainNotActiveError

ServiceBusyError

QueryFailedError

Rate Limiting

Best Practices

Idempotency

Long Polling

Pagination

Query Consistency

See Also