Matching Service API

Task queue management and task distribution service

The Matching Service manages task queues and distributes workflow and activity tasks to workers. It provides load balancing, task versioning, and worker management capabilities.

Overview

The Matching Service is responsible for:

• Managing task queues for workflows and activities
• Distributing tasks to available workers
• Task queue partitioning and load balancing
• Worker versioning and build ID compatibility
• Task queue user data and configuration
• Nexus endpoint management
• Worker heartbeat and health tracking

Service Methods

Task Polling

PollWorkflowTaskQueue

Polls for a workflow task from a task queue.

namespace_id · string · required

UUID of the namespace

poller_id · string · required

Unique identifier for the worker polling

poll_request · PollWorkflowTaskQueueRequest · required

Poll parameters including task queue name and worker identity

forwarded_source · string

Source partition if forwarded from another partition

task_token · bytes

Opaque token identifying the task

workflow_execution · WorkflowExecution

Workflow execution information

workflow_type · WorkflowType

Type of the workflow

started_event_id · int64

Event ID when task started

history · History

Workflow history events for the task

PollActivityTaskQueue

Polls for an activity task from a task queue.

namespace_id · string · required

Namespace UUID

poller_id · string · required

Unique poller identifier

poll_request · PollActivityTaskQueueRequest · required

Poll parameters

forwarded_source · string

Source partition if forwarded

task_token · bytes

Task token

workflow_execution · WorkflowExecution

Parent workflow execution

activity_id · string

Activity identifier

activity_type · ActivityType

Type of activity

input · Payloads

Activity input parameters

scheduled_time · Timestamp

When the activity was scheduled

current_attempt_scheduled_time · Timestamp

When current attempt was scheduled

PollNexusTaskQueue

Polls for a Nexus task from a task queue.

namespace_id · string · required

Namespace UUID

request · PollNexusTaskQueueRequest · required

Poll request with task queue and worker identity

task_token · bytes

Token for the Nexus task

request · Request

Nexus request details

Task Addition

AddWorkflowTask

Adds a workflow task to a task queue.

namespace_id · string · required

Namespace UUID

execution · WorkflowExecution · required

Workflow execution identifier

task_queue · TaskQueue · required

Target task queue

scheduled_event_id · int64 · required

Event ID when task was scheduled

source · TaskSource

Source of the task (history, backlog)

forwarded_source · string

Source if forwarded from another partition

response · AddWorkflowTaskResponse

Empty response on success

AddActivityTask

Adds an activity task to a task queue.

namespace_id · string · required

Namespace UUID

execution · WorkflowExecution · required

Parent workflow execution

task_queue · TaskQueue · required

Target task queue

scheduled_event_id · int64 · required

Event ID when activity was scheduled

source · TaskSource

Task source

forwarded_source · string

Forwarding source partition

response · AddActivityTaskResponse

Empty response on success

Query Management

QueryWorkflow

Forwards a workflow query to a worker.

namespace_id · string · required

Namespace UUID

task_queue · TaskQueue · required

Task queue where workflow is processing

query_request · QueryWorkflowRequest · required

Query parameters

forwarded_source · string

Source partition

query_result · Payloads

Result of the query

query_rejected · QueryRejected

Rejection details if query was rejected

RespondQueryTaskCompleted

Records completion of a query task.

namespace_id · string · required

Namespace UUID

task_queue · TaskQueue · required

Task queue

task_id · string · required

Query task identifier

completed_request · RespondQueryTaskCompletedRequest · required

Completion details

Nexus Operations

DispatchNexusTask

Dispatches a Nexus task to a worker.

namespace_id · string · required

Namespace UUID

task_queue · TaskQueue · required

Target task queue

request · Request · required

Nexus request to dispatch

response · Response

Nexus response from worker

RespondNexusTaskCompleted

Records successful completion of a Nexus task.

namespace_id · string · required

Namespace UUID

task_token · bytes · required

Nexus task token

response · Response · required

Task response

RespondNexusTaskFailed

Records failure of a Nexus task.

namespace_id · string · required

Namespace UUID

task_token · bytes · required

Nexus task token

error · Error · required

Failure error details

Nexus Endpoint Management

CreateNexusEndpoint

Creates a new Nexus endpoint.

spec · EndpointSpec · required

Endpoint specification including name, target

endpoint · Endpoint

Created endpoint with assigned ID

UpdateNexusEndpoint

Updates an existing Nexus endpoint.

id · string · required

Endpoint ID

version · int64 · required

Current version for optimistic concurrency

spec · EndpointSpec · required

Updated endpoint specification

endpoint · Endpoint

Updated endpoint

DeleteNexusEndpoint

Deletes a Nexus endpoint.

id · string · required

Endpoint ID to delete

version · int64 · required

Current version

response · DeleteNexusEndpointResponse

Empty response on success

ListNexusEndpoints

Lists all Nexus endpoints.

page_size · int32

Maximum endpoints per page

next_page_token · bytes

Pagination token

endpoints · Endpoint[]

List of endpoints

next_page_token · bytes

Token for next page

Task Queue Description

DescribeTaskQueue

Retrieves information about a task queue.

namespace_id · string · required

Namespace UUID

desc_request · DescribeTaskQueueRequest · required

Description request with task queue name and type

pollers · PollerInfo[]

List of active pollers

task_queue_status · TaskQueueStatus

Task queue status including backlog

versions · TaskQueueVersionInfo[]

Version information for versioned task queues

DescribeTaskQueuePartition

Retrieves information about a specific task queue partition.

namespace_id · string · required

Namespace UUID

task_queue · TaskQueue · required

Task queue identifier

partition_id · int32 · required

Partition ID

pollers · PollerInfo[]

Pollers on this partition

partition_config · PartitionConfig

Partition configuration

DescribeVersionedTaskQueues

Describes task queues with versioning information.

namespace_id · string · required

Namespace UUID

task_queue · TaskQueue · required

Task queue name

versions · TaskQueueVersionSelection

Version selection criteria

versioned_queues · VersionedTaskQueueInfo[]

Information for each versioned queue

ListTaskQueuePartitions

Lists all partitions for a task queue.

namespace · string · required

Namespace name

task_queue · TaskQueue · required

Task queue identifier

activity_task_queue_partitions · TaskQueuePartitionMetadata[]

Activity task queue partitions

workflow_task_queue_partitions · TaskQueuePartitionMetadata[]

Workflow task queue partitions

Worker Versioning

UpdateWorkerBuildIdCompatibility

Updates build ID compatibility rules for a task queue.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

operation · BuildIdOp · required

Build ID operation (add, promote, mark_default)

response · UpdateWorkerBuildIdCompatibilityResponse

Empty response on success

GetWorkerBuildIdCompatibility

Retrieves build ID compatibility rules.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

max_sets · int32

Maximum compatibility sets to return

major_version_sets · CompatibleVersionSet[]

Compatible version sets

UpdateWorkerVersioningRules

Updates versioning rules for workers.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

request · UpdateWorkerVersioningRulesRequest · required

Versioning rules update

response · UpdateWorkerVersioningRulesResponse

Updated rules

GetWorkerVersioningRules

Retrieves current versioning rules.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

assignment_rules · VersioningAssignmentRule[]

Assignment rules

redirect_rules · VersioningRedirectRule[]

Redirect rules

Task Queue User Data

GetTaskQueueUserData

Retrieves user data for a task queue.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

user_data · TaskQueueUserData

User data including versioning info

UpdateTaskQueueUserData

Updates user data for a task queue.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

user_data · TaskQueueUserData · required

Updated user data

build_ids · string[]

Associated build IDs

response · UpdateTaskQueueUserDataResponse

Empty response on success

ReplicateTaskQueueUserData

Replicates task queue user data across clusters.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

user_data · TaskQueueUserData · required

User data to replicate

Worker Management

RecordWorkerHeartbeat

Records a heartbeat from a worker.

namespace_id · string · required

Namespace UUID

worker_identity · string · required

Worker identity

task_queue · string · required

Task queue the worker is polling

response · RecordWorkerHeartbeatResponse

Empty response on success

ListWorkers

Lists workers polling a task queue.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

page_size · int32

Maximum workers per page

workers · WorkerInfo[]

List of worker information

DescribeWorker

Retrieves detailed information about a worker.

namespace_id · string · required

Namespace UUID

worker_identity · string · required

Worker identity

worker_info · WorkerInfo

Detailed worker information

Partition Management

ForceLoadTaskQueuePartition

Forces loading of a task queue partition.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

partition_id · int32 · required

Partition to load

response · ForceLoadTaskQueuePartitionResponse

Empty response on success

ForceUnloadTaskQueue

Forces unloading of a task queue.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue to unload

response · ForceUnloadTaskQueueResponse

Empty response on success

ForceUnloadTaskQueuePartition

Forces unloading of a specific partition.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

partition_id · int32 · required

Partition to unload

Additional Operations

CancelOutstandingPoll

Cancels an outstanding poll request.

namespace_id · string · required

Namespace UUID

task_queue_type · TaskQueueType · required

Type of task queue

task_queue · TaskQueue · required

Task queue identifier

poller_id · string · required

Poller to cancel

GetBuildIdTaskQueueMapping

Retrieves mapping between build IDs and task queues.

namespace_id · string · required

Namespace UUID

build_id · string · required

Build ID to query

task_queues · string[]

Task queues associated with the build ID

UpdateTaskQueueConfig

Updates configuration for a task queue.

namespace_id · string · required

Namespace UUID

task_queue · string · required

Task queue name

config · TaskQueueConfig · required

Configuration to apply

response · UpdateTaskQueueConfigResponse

Empty response on success

Usage Notes

• Long polling is used for task distribution with configurable timeouts
• Task queue partitioning enables horizontal scaling
• Worker versioning supports gradual rollouts and compatibility management
• Sticky task queues improve workflow task performance
• The service handles automatic task forwarding between partitions

See Also

• History Service API
• Frontend Service API
• Worker Versioning Guide