Skip to Content

Embeds

Rename a filter in an embed

Give a dashboard or metric filter your own label for one customer or for all of them.

POST
/api/v2/dashboard/updateDashboardFilterAlias

Your app calls this with a guest token, for the customer who is viewing. The alias shows instead of the filter name.

curl --request POST https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias \  --header "X-Plugin-Token: $GUEST_TOKEN" \  --header "Content-Type: application/json" \  --data '{ "externalDashboard": "sales-overview", "filterKey": "public.orders.region", "alias": "Sales region" }'

For a metric filter, call POST /api/v2/dashboard/updateMetricFilterAlias with externalMetricId instead of externalDashboard.

Auth

A guest token in the X-Plugin-Token header, not a Bearer token. The guest token needs params.accessPermissions.isAllowDashboardFilterNameChange (or isAllowMetricFilterNameChange for a metric) set to true. See Create a guest token.

A guest token that sees all tenants sets the alias for every customer. Otherwise it is set for the token's clientId only.

Body

externalDashboardstringrequired

Required dashboard. The dashboard's externalDashboardId

Required metric. The metric id.

filterKeystringrequired

The filter's column as table.column, for example public.orders.region. Letter case does not matter.

aliasstringrequired

The new label, up to 100 characters. "" removes the alias.

Only filters that you made in the app can get an alias, not filters a customer added.

Response

{ "data": { "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "filterKey": "public.orders.region", "alias": "Sales region" } }

When you remove the alias, id is not in the response.

Errors

This endpoint puts the error in data.error:

{ "data": { "error": { "message": "Invalid dashboard filter" } } }
StatusMessageWhy
400Invalid dashboard filter alias payloadA field is missing or empty
400Dashboard filter alias is too longalias is over 100 characters
400Invalid dashboard filterNo filter on the dashboard has this filterKey
403UNAUTHORIZEDThe guest token may not rename filters, or the dashboard is outside it
404Dashboard not found or Metric not foundThe id is unknown

The metric endpoint returns the same messages with metric instead of dashboard.

Example Request
curl -X POST 'https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias' \  -H 'Content-Type: application/json' \  -d '{  "externalDashboard": "sales-overview",  "filterKey": "public.orders.region",  "alias": "Sales region"}'
Example Response
{  "data": {    "filterKey": "public.orders.region",    "alias": ""  }}