# deleteLabel

Mutation

Schedule deletion of one label across the whole workspace; deletion is asynchronous and irreversible, and the creators survive.

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

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `labelName` | `String!` | Yes | — | The label to delete, exactly as the `labels` query returns it. A name is the label identity — labels have no id in this API — and matching ignores case and surrounding whitespace, so any spelling of the same label deletes it. Deletion is workspace-wide and irreversible: the label leaves the taxonomy AND every creator carrying it. A blank name is rejected. Not length-limited: a label longer than the creation limit stays deletable. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `labelName` | `String!` | The label name you submitted, echoed back verbatim — never the workspace's stored spelling. |
| `operationId` | `ID` | The `delete_label` operation that owns this label's deletion; 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 deletion is scheduled — including when this label's deletion was already in flight, in which case `operationId` is that deletion's operation. False when userErrors is non-empty. Deletion is asynchronous. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | Errors that refused the request: a blank name, a name matching no label in this workspace, or a workspace with no user to attribute the deletion to. Empty on success. |

## Examples

### Delete a label

Schedule the workspace-wide deletion of a label; the creators carrying it are kept.

```graphql
mutation DeleteLabelDefault($labelName: String!) {
  deleteLabel(labelName: $labelName) {
    scheduled
    operationId
    labelName
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "labelName": "Retired 2024"
}
```

Response — HTTP 200:

```json
{
  "data": {
    "deleteLabel": {
      "scheduled": true,
      "operationId": "d6d1a270-cb9a-57fc-8c4c-e101c51e79d5",
      "labelName": "Retired 2024",
      "userErrors": []
    }
  }
}
```