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

# Update Embedded Filter Alias

> Rename dashboard and metric filter labels for an embedded end user.

Update the label shown for an existing dashboard or metric filter in an embedded experience. These are end-user plugin APIs: authenticate with a guest token in `X-Plugin-Token`, not with a Data App API key.

<Note>
  Enable the matching rename permission in `params.accessPermissions` when you mint the guest token: `isAllowDashboardFilterNameChange` for dashboard filters or `isAllowMetricFilterNameChange` for metric filters.
</Note>

## Endpoints

### Cloud Databrain

```http theme={"dark"}
POST https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias
POST https://api.usedatabrain.com/api/v2/dashboard/updateMetricFilterAlias
```

### Self-hosted Databrain

```http theme={"dark"}
POST <SELF_HOSTED_URL>/api/v2/dashboard/updateDashboardFilterAlias
POST <SELF_HOSTED_URL>/api/v2/dashboard/updateMetricFilterAlias
```

## Authentication

<ParamField header="X-Plugin-Token" type="string" required>
  Guest token generated by the [Guest Token API](/developer-docs/helpers/api-reference/token). The token determines the dashboard, metric, workspace, and client scope for the request.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`.
</ParamField>

## Update a dashboard filter alias

<ParamField body="externalDashboard" type="string" required>
  Dashboard identifier. The API accepts the dashboard's internal UUID or its external dashboard ID.
</ParamField>

<ParamField body="filterKey" type="string" required>
  Case-insensitive dashboard filter key in the form `tableName.columnName`, for example `public.sales_data.region`. The filter must already exist and must not be a client-created dashboard filter.
</ParamField>

<ParamField body="alias" type="string" required>
  New label for the filter. Leading and trailing whitespace is removed and the trimmed value can be at most 100 characters. Send an empty string to clear the alias.
</ParamField>

```bash cURL theme={"dark"}
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias \
  --header 'X-Plugin-Token: <GUEST_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalDashboard": "dashboard-uuid-or-external-id",
    "filterKey": "public.sales_data.region",
    "alias": "Sales region"
  }'
```

## Update a metric filter alias

<ParamField body="externalMetricId" type="string" required>
  Metric identifier. The API accepts the metric's internal UUID or metric ID.
</ParamField>

<ParamField body="filterKey" type="string" required>
  Case-insensitive metric filter key in the form `tableName.columnName`, for example `public.sales_data.region`. The filter must already exist.
</ParamField>

<ParamField body="alias" type="string" required>
  New label for the filter. Leading and trailing whitespace is removed and the trimmed value can be at most 100 characters. Send an empty string to clear the alias.
</ParamField>

```bash cURL theme={"dark"}
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/dashboard/updateMetricFilterAlias \
  --header 'X-Plugin-Token: <GUEST_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalMetricId": "metric-uuid-or-id",
    "filterKey": "public.sales_data.region",
    "alias": "Sales region"
  }'
```

## Response

Both endpoints return the updated alias in the `data` object:

```json theme={"dark"}
{
  "data": {
    "id": "alias_abc123",
    "filterKey": "public.sales_data.region",
    "alias": "Sales region"
  }
}
```

When `alias` is an empty string, the endpoint removes the stored alias and returns:

```json theme={"dark"}
{
  "data": {
    "filterKey": "public.sales_data.region",
    "alias": ""
  }
}
```

## Status codes

| Status | Description                                                                                                             |
| ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `200`  | Alias updated or cleared successfully.                                                                                  |
| `400`  | Missing or invalid body fields, an unknown filter, or an alias longer than 100 characters.                              |
| `403`  | The guest token is not authorized for the requested dashboard or metric, or the matching rename permission is disabled. |
| `404`  | The dashboard or metric was not found in the guest token's authorized scope.                                            |
| `500`  | The alias could not be persisted or an unexpected server error occurred.                                                |