---
title: "Merge Labels"
description: "Merge one label into another: every place the source label is applied moves onto the target (a span that had both keeps one), then the source is archived with mergedInto set."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Merge Labels

Use the Speak AI MCP server tool `merge_labels` to merge one label into another:
every place the source label is applied moves onto the target (a span that had both
keeps one), then the source is archived with mergedInto set.

## What does it do?

Merge one label into another: every place the source label is applied moves onto the
target (a span that had both keeps one), then the source is archived with mergedInto
set. This cannot be undone by `restore_label`. Both must be active, non-group labels
and different. Returns movedCount. Requires both the labels update and labels delete
permissions; only owners and admins have labels delete by default. The change is
recorded in your Speak Notifications under Label (type label).

## Parameters

`merge_labels` takes 2 parameters, all of them required.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `labelId` | string | Yes | The label to merge away (it is archived) |
| `targetLabelId` | string | Yes | The label that receives every use of labelId |

## Behaviour

The Speak AI MCP server publishes these behaviour hints for `merge_labels`.

- Can change data in your workspace.
- Can delete or overwrite data. Use with care.
- Repeating an identical call can have an extra effect.
- Stays inside Speak AI. Does not reach other systems.

## Related

- [Labels & comments](/mcp/tools/labels-comments/) lists the rest of the Labels &
  comments category.
- [Tool reference](/mcp/tools/) lists every Speak AI MCP server tool.
- [MCP server](/mcp/) covers setup, supported clients, and what agents can do once
  connected.

Source: https://docs.speakai.co/mcp/tools/labels-comments/merge_labels/index.mdx