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

# update_group_dimension

> Rename a group dimension, change its key or its description. Its groups are left as they are.

Rename a group dimension, change its key or its description.

Pass at least one of `name`, `key` or `description` — a call with none of them
has nothing to update. Sending the values the dimension already has changes
nothing, so the same call can be sent twice.

A rename reaches every report that breaks down by the dimension, which reads
under its new name there once the background propagation has run. The
dimension's groups are left as they are: rename one with
[`update_group`](https://docs.qobra.co/mcp_documentation/tools/update_group).

The call is refused when the new key is already carried by another dimension of
the company.

Requires write permission on groups. Available only where the Qobra write tools
beta is enabled. Every write is recorded in the audit trail as the `Qobra MCP`
agent.

```json Example arguments theme={null}
{
  "dimension_id": "665f1c2e8a4b3d0012a7e9f1",
  "name": "Sales region",
  "description": "Where the rep sells, as set in the HRIS."
}
```

## Parameters

> **Body**
>
> **dimension\_id** `string` *required*
>
> Id of the dimension to update — the id list\_group\_dimensions returns, or
> the one create\_group\_dimension just returned.
>
> **name** `string`
>
> New display name for the grouping axis. Omit to leave the current name as
> it is.
>
> **key** `string`
>
> New stable key for the dimension — the identifier an integration matches
> it on, distinct from the display name. Omit to leave the current key as it
> is.
>
> **description** `string`
>
> New free-text note about what the axis groups, replacing the current one
> whole. Pass an empty string to clear it. Omit to leave the current
> description as it is.

## Response

> **Body**
>
> **dimension** `object`
>
> The dimension as it now stands after the update — the same shape
> list\_group\_dimensions returns.
>
> **object properties**
>
> **id** `string`
>
> **name** `string`
>
> **key** `string`
>
> The dimension's stable key — the identifier used to match it when
> synced from an integration, distinct from its display name.
>
> **description** `string`
>
> Free-text note about what the axis groups, as the web app shows it
> under the dimension's name. Null when it has none.
>
> **archived** `boolean`
>
> **group\_count** `integer`
>
> Number of groups that belong to this dimension.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.