---
title: "Rename Cluster Labels (Per-Execution)"
method: PATCH
path: "/v1/clusters/{cluster_id}/executions/{run_id}/labels"
tags: ["Cluster Executions"]
---

# Rename Cluster Labels (Per-Execution)

`PATCH /v1/clusters/{cluster_id}/executions/{run_id}/labels`

Rename cluster labels for a single execution — no re-run required.

    Entries merge into the execution record's `label_overrides` map
    (per-key upsert): a non-empty value sets/replaces the override for that
    cluster_id, an empty string deletes it (restoring the original LLM/auto
    label). Overrides are applied server-side wherever labels are read —
    execution GETs (`centroids[].label`) and the cluster visualization
    endpoint (`cluster_label` on centroid points) — so all clients agree.

    Overrides are per-run because cluster ids (`cl_0`, `cl_1`, ...) are
    assigned per-run: a rename on one execution never leaks onto another.

    Example body: `{"labels": {"cl_0": "Gadget Reviews", "cl_2": ""}}`
    (renames cl_0, deletes any override on cl_2).

## Path parameters

- `cluster_id` string, required — Cluster ID
- `run_id` string, required — Run ID whose labels to rename

## Request body

- PatchExecutionLabelsRequest — Body for PATCH /v1/clusters/{cluster_id}/executions/{run_id}/labels. Renames cluster labels for a single execution without re-running clustering. Entries merge into the execution record's ``label_overrides`` map (per-key upsert); an empty-string value deletes that key's override, restoring the original (LLM/auto) label.
  - `labels` object, required — Map of cluster_id -> new label (e.g. {'cl_0': 'Gadget Reviews'}). Values are trimmed; a non-empty value sets/replaces the override for that cluster_id, an empty string deletes it. Labels are capped at 200 characters. At least one entry is required.

## Response `200`

Successful Response

- PatchExecutionLabelsResponse — Response for PATCH .../executions/{run_id}/labels: the merged overrides.
  - `cluster_id` string, required — Cluster the execution belongs to
  - `run_id` string, required — Execution whose labels were patched
  - `label_overrides` object — The execution's full label_overrides map AFTER applying this patch (merged; deleted keys removed). Empty dict when the last override was just deleted.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

## Changes

- **2026-08-09** `5d4c905106b4` — 1 info
  - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API

[Change history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/clusters/:cluster_id/executions/:run_id/labels/patch.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/daf60765b81d/schema)