# mergeLabels

Mutation

Fold one label into another across the whole workspace; asynchronous and irreversible — every creator carrying it ends up on the target, and the source label is deleted.

Available to agents as MCP tool `mergeLabels` — see [Write tools](/api/v2/docs/mcp/write-tools#merge-labels).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `intoLabelName` | `String!` | Yes | — | The existing label that absorbs it, exactly as the `labels` query returns it. It must already exist; the same label in any spelling is refused (use `renameLabel` to respell). A blank name is rejected. |
| `labelName` | `String!` | Yes | — | The label to fold in, exactly as the `labels` query returns it. It stops existing once the merge completes. Matching ignores case and surrounding whitespace. A blank name is rejected. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `operationId` | `ID` | The `merge_labels` operation that runs this merge; poll it with `operation(id:)`. Null when userErrors is non-empty. A label operation tracks progress with `status`, `total` and `processed` only — its record-derived counts are always 0 and its item-id lists always empty. |
| `scheduled` | `Boolean!` | True when the merge is scheduled; `operationId` is then set. False when userErrors is non-empty. The merge is asynchronous. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | Errors that refused the request, on the input at fault: a blank name, a label that does not exist or is being deleted, a label already being merged, the same label on both sides, a label stored under several spellings, or no user to attribute the merge to. Empty on success. |

## Examples

### Merge two labels

Schedule folding one label into another existing label; the merged label is deleted.

```graphql
mutation MergeLabelsDefault($labelName: String!, $intoLabelName: String!) {
  mergeLabels(labelName: $labelName, intoLabelName: $intoLabelName) {
    scheduled
    operationId
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "labelName": "Retired 2024",
  "intoLabelName": "Gifting"
}
```

Response — HTTP 200:

```json
{
  "data": {
    "mergeLabels": {
      "scheduled": true,
      "operationId": "d0e2a7ec-c713-539e-bcc7-ae6fe33da461",
      "userErrors": []
    }
  }
}
```