---
title: "Update Media Label"
description: "Change a labelled span on a transcript."
---

> 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.

# Update Media Label

`update_media_label` is a tool in the Speak AI MCP server. Change a labelled span on
a transcript.

## What does it do?

Change a labelled span on a transcript. Do exactly one of: labelIds to replace its
labels; action keep to confirm its current anchor (after the transcript was edited
and its status is shifted or needs_review); or action replace with a new quote or
range to move it. A 409 that says the transcript changed means someone edited it
after your revision was read: read the transcript again (`get_transcript`) and retry
with the new range or quote. Nothing was saved. Keep also answers 409 when the
anchor was built on an older revision: `list_media_labels` again first. Requires the
labels assign permission (every member by default). The change is recorded in your
Speak Notifications under Label (type label).

## Parameters

`update_media_label` takes 8 parameters, 2 of them required.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `mediaId` | string | Yes | Media id |
| `mediaLabelId` | string | Yes | mediaLabelId from `list_media_labels` |
| `labelIds` | array of string | No | 1 to 20 distinct ids of active labels (not groups), from `list_labels` |
| `action` | enum | No | keep confirms the current anchor; replace moves the span to quote or range |
| `range` | object | No | Exact word range. Needs expectedTranscriptRevision. Prefer quote unless you already hold word indices. Word indices count the words of `get_transcript`'s insight.transcript in order, from 0: for each sentence, the words of its entities[].text when it has entities, otherwise its text split on spaces; tokens that are only punctuation are not counted. |
| `expectedTranscriptRevision` | number | No | transcriptRevision the range was read at (returned by `get_transcript`, `list_media_labels` and `list_media_comments`). Required with range. Optional with quote: the quote is found in the current transcript, and a revision you pass makes the call fail with 409 if the transcript changed since you read it. |
| `quote` | string | No | Words copied from the transcript, used instead of range. Matching ignores case and leading or trailing punctuation, and must cover whole words in order. If the words appear more than once, pass occurrence. |
| `occurrence` | number | No | Which match of quote to use (1 = first) when the quote appears more than once |

## Behaviour

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

- Can change data in your workspace.
- Can delete or overwrite data. Use with care.
- Repeating an identical call is safe.
- 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/update_media_label/index.mdx