> ## 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. # 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. UUID of the namespace Unique identifier for the worker polling Poll parameters including task queue name and worker identity Source partition if forwarded from another partition Opaque token identifying the task Workflow execution information Type of the workflow Event ID when task started Workflow history events for the task #### PollActivityTaskQueue Polls for an activity task from a task queue. Namespace UUID Unique poller identifier Poll parameters Source partition if forwarded Task token Parent workflow execution Activity identifier Type of activity Activity input parameters When the activity was scheduled When current attempt was scheduled #### PollNexusTaskQueue Polls for a Nexus task from a task queue. Namespace UUID Poll request with task queue and worker identity Token for the Nexus task Nexus request details ### Task Addition #### AddWorkflowTask Adds a workflow task to a task queue. Namespace UUID Workflow execution identifier Target task queue Event ID when task was scheduled Source of the task (history, backlog) Source if forwarded from another partition Empty response on success #### AddActivityTask Adds an activity task to a task queue. Namespace UUID Parent workflow execution Target task queue Event ID when activity was scheduled Task source Forwarding source partition Empty response on success ### Query Management #### QueryWorkflow Forwards a workflow query to a worker. Namespace UUID Task queue where workflow is processing Query parameters Source partition Result of the query Rejection details if query was rejected #### RespondQueryTaskCompleted Records completion of a query task. Namespace UUID Task queue Query task identifier Completion details ### Nexus Operations #### DispatchNexusTask Dispatches a Nexus task to a worker. Namespace UUID Target task queue Nexus request to dispatch Nexus response from worker #### RespondNexusTaskCompleted Records successful completion of a Nexus task. Namespace UUID Nexus task token Task response #### RespondNexusTaskFailed Records failure of a Nexus task. Namespace UUID Nexus task token Failure error details ### Nexus Endpoint Management #### CreateNexusEndpoint Creates a new Nexus endpoint. Endpoint specification including name, target Created endpoint with assigned ID #### UpdateNexusEndpoint Updates an existing Nexus endpoint. Endpoint ID Current version for optimistic concurrency Updated endpoint specification Updated endpoint #### DeleteNexusEndpoint Deletes a Nexus endpoint. Endpoint ID to delete Current version Empty response on success #### ListNexusEndpoints Lists all Nexus endpoints. Maximum endpoints per page Pagination token List of endpoints Token for next page ### Task Queue Description #### DescribeTaskQueue Retrieves information about a task queue. Namespace UUID Description request with task queue name and type List of active pollers Task queue status including backlog Version information for versioned task queues #### DescribeTaskQueuePartition Retrieves information about a specific task queue partition. Namespace UUID Task queue identifier Partition ID Pollers on this partition Partition configuration #### DescribeVersionedTaskQueues Describes task queues with versioning information. Namespace UUID Task queue name Version selection criteria Information for each versioned queue #### ListTaskQueuePartitions Lists all partitions for a task queue. Namespace name Task queue identifier Activity task queue partitions Workflow task queue partitions ### Worker Versioning #### UpdateWorkerBuildIdCompatibility Updates build ID compatibility rules for a task queue. Namespace UUID Task queue name Build ID operation (add, promote, mark\_default) Empty response on success #### GetWorkerBuildIdCompatibility Retrieves build ID compatibility rules. Namespace UUID Task queue name Maximum compatibility sets to return Compatible version sets #### UpdateWorkerVersioningRules Updates versioning rules for workers. Namespace UUID Task queue name Versioning rules update Updated rules #### GetWorkerVersioningRules Retrieves current versioning rules. Namespace UUID Task queue name Assignment rules Redirect rules ### Task Queue User Data #### GetTaskQueueUserData Retrieves user data for a task queue. Namespace UUID Task queue name User data including versioning info #### UpdateTaskQueueUserData Updates user data for a task queue. Namespace UUID Task queue name Updated user data Associated build IDs Empty response on success #### ReplicateTaskQueueUserData Replicates task queue user data across clusters. Namespace UUID Task queue name User data to replicate ### Worker Management #### RecordWorkerHeartbeat Records a heartbeat from a worker. Namespace UUID Worker identity Task queue the worker is polling Empty response on success #### ListWorkers Lists workers polling a task queue. Namespace UUID Task queue name Maximum workers per page List of worker information #### DescribeWorker Retrieves detailed information about a worker. Namespace UUID Worker identity Detailed worker information ### Partition Management #### ForceLoadTaskQueuePartition Forces loading of a task queue partition. Namespace UUID Task queue name Partition to load Empty response on success #### ForceUnloadTaskQueue Forces unloading of a task queue. Namespace UUID Task queue to unload Empty response on success #### ForceUnloadTaskQueuePartition Forces unloading of a specific partition. Namespace UUID Task queue name Partition to unload ### Additional Operations #### CancelOutstandingPoll Cancels an outstanding poll request. Namespace UUID Type of task queue Task queue identifier Poller to cancel #### GetBuildIdTaskQueueMapping Retrieves mapping between build IDs and task queues. Namespace UUID Build ID to query Task queues associated with the build ID #### UpdateTaskQueueConfig Updates configuration for a task queue. Namespace UUID Task queue name Configuration to apply 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](/api/history-service) * [Frontend Service API](/api/frontend-service) * [Worker Versioning Guide](/guides/worker-versioning)