Custom metrics

List custom metrics

dashboards.custom_metrics.list

Lists all the workspace's custom metrics (from an account, its workspace's; up to 50), by name: formula and its readable text, format (number, currency, percent), decimals, whether higher is better, platforms, is_blended (more than one platform: usable in KPIs and charts, not in tables) and who created it (created_by_id, created_by_name). Widgets reference a custom metric by its public_id (custom:<id>).

Scope

dashboards:read

Permission

View the module

MCP tool

dashboards_custom_metrics_listOn the full surface; on the compact one, mb_execute_operation with id: "dashboards.custom_metrics.list".

Declared cost: up to 51 reads and 0 writes per call (they count against the daily quota).

Parameters

No parameters.

Response

Errors

Example

curl "https://api.mb-suite.com/v1/dashboards/custom-metrics" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/dashboards/custom-metrics" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a custom metric

dashboards.custom_metrics.create

Creates a custom metric in the workspace (not in an account: workspace_only) with a unique name (max 60), optional description, formula, format, decimals (0-4) and higher_is_better. The formula is a tree: {kind: 'metric', metric_id, platform} (a metric id of that platform's registry, numeric), {kind: 'constant', value}, {kind: 'binary', op: '+'|'-'|'*'|'/', left, right} or {kind: 'group', child} (parentheses); up to 20 metrics and 12 levels, never another custom metric. Up to 50 per workspace. Returns the new id; widgets use custom:<id>. Requires edit access to Dashboards in the workspace.

Scope

dashboards:write

Permission

Edit in the module

MCP tool

dashboards_custom_metrics_createOn the full surface; on the compact one, mb_execute_operation with id: "dashboards.custom_metrics.create".

Declared cost: up to 51 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/dashboards/custom-metrics" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "formula": "FORMULA",
  "format": "number",
  "decimals": 0,
  "higher_is_better": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/dashboards/custom-metrics" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "formula": "FORMULA",
  "format": "number",
  "decimals": 0,
  "higher_is_better": true
}'

Update a custom metric

dashboards.custom_metrics.update

Updates any of the name, description (empty clears it), formula, format, decimals and higher_is_better of a workspace custom metric; what is not sent is kept. The formula is a tree: {kind: 'metric', metric_id, platform} (a metric id of that platform's registry, numeric), {kind: 'constant', value}, {kind: 'binary', op: '+'|'-'|'*'|'/', left, right} or {kind: 'group', child} (parentheses); up to 20 metrics and 12 levels, never another custom metric. Every widget that uses it shows the new definition. Returns the updated metric. Requires edit access to Dashboards in the workspace.

Scope

dashboards:write

Permission

Edit in the module

MCP tool

dashboards_custom_metrics_updateOn the full surface; on the compact one, mb_execute_operation with id: "dashboards.custom_metrics.update".

Declared cost: up to 52 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/dashboards/custom-metrics/{metric_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/dashboards/custom-metrics/{metric_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a custom metric

dashboards.custom_metrics.delete

Deletes a workspace custom metric. It goes to the 30-day trash; widgets and report blocks that use it show an error until it is restored. Outside the screen it requires a dry run and a confirm_token, except a plain REST DELETE with a key allowed to delete. Requires edit access to Dashboards in the workspace.

With an API key, this DELETE runs directly: the record stays 30 days in the trash and the response carries its trash_item_id. With an OAuth token, and through the MCP, it needs dry_run → confirm_token.

Scope

dashboards:write and “Allow deletions” (dashboards:delete in OAuth)

Permission

Edit in the module

MCP tool

dashboards_custom_metrics_deleteOn the full surface; on the compact one, mb_execute_operation with id: "dashboards.custom_metrics.delete".

Declared cost: up to 1 reads and 2 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/dashboards/custom-metrics/{metric_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/dashboards/custom-metrics/{metric_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"