Skip to main content

list-custom-metrics

dci list-custom-metrics [flags]

Returns a page of the customer's custom metrics. Preset metrics are not included. Requires the analytics:calculatedMetrics entitlement and a metrics read permission.

rowCount is the exact number of metrics that match nameContains and filter, across all pages. The page token is opaque and bound to nameContains, filter, sortBy and sortOrder: reusing it with different values gets 400 pagination_token_invalid.

Errors (RFC 9457 Problem Details, code field):

  • 400 validation_failed: a bad parameter, such as maxResults over 500 or an unknown sortBy value.
  • 400 filter_key_not_supported: a filter key other than name or owner. The details entry lists the supported keys in supportedKeys.
  • 400 pagination_token_invalid: see above.
  • 400 tenant_id_required: a caller with access to more than one customer sent no X-Tenant-Id.
  • 403 analytics.feature_not_entitled: the customer does not have the calculated metrics entitlement.
  • 403 forbidden: no metrics read permission, or an X-Tenant-Id that the credential cannot access.

maxResults is at most 500. A larger value returns 400 validation_failed.

sortOrder defaults to desc.

Flags​

FlagTypeDefaultExampleDescription
--max-resultsinteger (int64)50The maximum number of results to return in a single page. Use the page tokens to iterate through the entire collection.
--page-tokenstringPage token, returned by a previous call, to request the next page of results
--name-containsstringmonthly spendCase-insensitive substring match against the resource name. Combined with the "filter" parameter using AND semantics.
--filterstringowner:finops%40example.comFilter as key:value pairs, | between keys. Keys, operand types and operators: - name — string; operator eq. Exact, case-sensitive match. Comma-separated values for OR. - owner — owner email; operator eq. Exact match. Comma-separated values for OR. Any other key returns 400 filter_key_not_supported. For example owner:finops%40example.com. Use nameContains for a substring match on the name. Percent-encode ,, |, : and spaces inside values.
--sort-bystring"update_time"update_timeField to sort by. Ties break by id, so paging never repeats or skips a metric. One of: "name", "create_time", "update_time".
--sort-orderstringSpecifies the sort direction; accepts asc for ascending (lowest to highest) or desc for descending (highest to lowest). One of: "asc", "desc".

Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.

Output​

A page of custom metrics, most recently updated first by default.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
itemsarray of anyResource instances in the current page. Per-resource schemas replace items[] with array<ResourceType>.
pageTokenstringOpaque continuation token. Present only when more results are available; absent on the final page. Clients pass this back verbatim as the pageToken query parameter to fetch the next page.
rowCountinteger (int64)Optional best-effort total-count hint. Servers include this when computing it is cheap (indexed count) and MAY return null or omit it for expensive-to-count endpoints. Clients MUST NOT assume this field is present or non-null. When present, it is the total across all pages, not just the current page.

Example response (--output json)​

{
"items": [
{
"id": "m8Tq2LxV4cRn7YpB1sKd",
"etag": "\"9f2c4e1a7b3d\"",
"name": "Cost per ride",
"description": "Total cost divided by reported rides",
"owner": "[email protected]",
"variables": [
{
"letter": "A",
"metric": {
"type": "basic",
"value": "cost"
},
"allocationId": "aL1oC9tR2iDe5Kq7Zw3x"
},
{
"letter": "B",
"metric": {
"type": "basic",
"value": "usage"
},
"allocationId": "bU4sG6eR8iDe0Mn2Jp5y"
}
],
"formula": "A/B",
"unitType": "number",
"decimals": {
"min": 0,
"max": 2
},
"createTime": "2026-10-12T09:30:00Z",
"updateTime": "2026-10-12T09:30:00Z"
}
],
"pageToken": "example-token-for-the-next-page",
"rowCount": 2
}
Raw JSON schema
{
"description": "A page of custom metrics.",
"allOf": [
{
"description": "Base envelope every list response inherits from: `items` plus the\noptional `pageToken` / `rowCount` pagination fields. The `pageToken` is\nopaque, encodes the sort state, and is rejected on a continuation with\na mismatched sort (`400 pagination_token_invalid`).\n",
"type": "object",
"additionalProperties": false,
"required": [
"items"
],
"properties": {
"items": {
"description": "Resource instances in the current page. Per-resource schemas replace\n`items[]` with `array<ResourceType>`.\n",
"type": "array",
"items": {}
},
"pageToken": {
"description": "Opaque continuation token. Present only when more results are available;\nabsent on the final page. Clients pass this back verbatim as the\n`pageToken` query parameter to fetch the next page.\n",
"type": "string",
"example": "eyJvZmZzZXQiOjUwLCJzb3J0IjoiY3JlYXRlVGltZSJ9"
},
"rowCount": {
"description": "Optional best-effort total-count hint. Servers include this when\ncomputing it is cheap (indexed count) and MAY return `null` or omit it\nfor expensive-to-count endpoints. Clients MUST NOT assume this field\nis present or non-null. When present, it is the total across all\npages, not just the current page.\n",
"type": "integer",
"nullable": true,
"format": "int64",
"minimum": 0,
"example": 137
}
}
},
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"description": "A custom metric.",
"example": {
"id": "m8Tq2LxV4cRn7YpB1sKd",
"etag": "\"9f2c4e1a7b3d\"",
"name": "Cost per ride",
"description": "Total cost divided by reported rides",
"owner": "[email protected]",
"variables": [
{
"letter": "A",
"metric": {
"type": "basic",
"value": "cost"
},
"allocationId": "aL1oC9tR2iDe5Kq7Zw3x"
},
{
"letter": "B",
"metric": {
"type": "basic",
"value": "usage"
},
"allocationId": "bU4sG6eR8iDe0Mn2Jp5y"
}
],
"formula": "A/B",
"unitType": "number",
"decimals": {
"min": 0,
"max": 2
},
"createTime": "2026-10-12T09:30:00Z",
"updateTime": "2026-10-12T09:30:00Z"
},
"required": [
"id",
"etag",
"name",
"description",
"owner",
"variables",
"formula",
"unitType",
"decimals",
"createTime",
"updateTime"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "Identifier of the metric. Reports use it in `metric: {type: custom, value: <id>}`.",
"example": "m8Tq2LxV4cRn7YpB1sKd"
},
"etag": {
"type": "string",
"readOnly": true,
"pattern": "^\"[!-~]+\"$",
"description": "Strong entity tag, the same value as the `ETag` header. It changes on every update. Send it in `If-Match`.",
"example": "\"9f2c4e1a7b3d\""
},
"name": {
"type": "string",
"description": "Name of the metric, exactly as sent. It is not trimmed.",
"example": "Cost per ride"
},
"description": {
"type": "string",
"description": "Description of the metric, exactly as sent. An empty string when there is none.",
"example": "Total cost divided by reported rides"
},
"owner": {
"type": "string",
"format": "email",
"readOnly": true,
"description": "Email of the owner.",
"example": "[email protected]"
},
"variables": {
"type": "array",
"description": "The variables, in letter order. The first is `A`.",
"minItems": 1,
"maxItems": 5,
"items": {
"type": "object",
"additionalProperties": false,
"description": "One variable of a metric, as returned.",
"required": [
"letter",
"metric",
"allocationId"
],
"properties": {
"letter": {
"type": "string",
"readOnly": true,
"pattern": "^[A-E]$",
"description": "Letter of the variable in the formula, from its position: `A` for the first, up to `E`.",
"example": "A"
},
"metric": {
"type": "object",
"additionalProperties": false,
"description": "The metric a variable measures, the same in requests and responses. Same shape as a report's `metric`, without `custom`: a custom metric cannot be a variable of another.",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"basic",
"extended"
],
"description": "`basic` for a cost, usage or savings metric. `extended` for an extended metric, such as a DataHub or GenAI metric.",
"example": "basic"
},
"value": {
"type": "string",
"minLength": 1,
"description": "For `basic`: `cost`, `usage` or `savings` (any other value returns `issue: value_not_in_enum`). For `extended`: the `key` of an item that `GET /analytics/v1/extended-metrics?filter=dataSource:billing,billing-datahub` lists, the same key a report uses in `metric: {type: extended, value: <key>}`. Any other key returns `issue: extended_metric_not_found`.",
"example": "cost"
}
}
},
"allocationId": {
"type": "string",
"description": "Identifier of the single allocation the variable measures.",
"example": "aL1oC9tR2iDe5Kq7Zw3x"
}
}
},
"example": [
{
"letter": "A",
"metric": {
"type": "basic",
"value": "cost"
},
"allocationId": "aL1oC9tR2iDe5Kq7Zw3x"
},
{
"letter": "B",
"metric": {
"type": "basic",
"value": "usage"
},
"allocationId": "bU4sG6eR8iDe0Mn2Jp5y"
}
]
},
"formula": {
"type": "string",
"minLength": 1,
"pattern": "^[A-E0-9+*/(). -]+$",
"description": "Arithmetic over the variable letters. Allowed: the letters of the\ndefined variables (`A` to `E`), numbers such as `100` or `0.5`, the\noperators `+`, `-`, `*` and `/`, parentheses and spaces. Spaces are\nignored when the formula is checked and evaluated, but the formula is\nstored and returned exactly as sent: `A / B` stays `A / B`. A minus\ncan be unary (`-A`, `A*-B`).\n\nRejected with `issue: invalid_formula`: a formula that starts with\n`+`, `*` or `/`, ends with an operator, has two binary operators in a\nrow, has empty or unbalanced parentheses, or divides by a literal\n`0`. Rejected with `issue: unknown_variable`: a letter with no\nvariable, such as `C` when there are two variables. A variable that\nthe formula does not use is allowed.\n",
"example": "A/B"
},
"unitType": {
"type": "string",
"enum": [
"number",
"percentage",
"currency"
],
"default": "number",
"description": "How reports show the value: a plain `number`, a `percentage`, or a `currency` amount in the customer's currency.",
"example": "number"
},
"decimals": {
"description": "Display precision, or `null` when the metric has none and reports use their default formatting. The server never fills in a value: a metric created without `decimals`, or updated with `decimals: null`, returns `null` from create, update and get alike.",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Number of decimal places reports show, from `min` to `max`. `min` must not be greater than `max`.",
"required": [
"min",
"max"
],
"properties": {
"min": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"description": "Fewest decimal places shown. Not greater than `max`.",
"example": 0
},
"max": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"description": "Most decimal places shown. Not less than `min`.",
"example": 2
}
}
}
],
"nullable": true,
"example": {
"min": 0,
"max": 2
}
},
"createTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "When the metric was created (RFC 3339, UTC).",
"example": "2026-10-12T09:30:00Z"
},
"updateTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "When the metric was last changed (RFC 3339, UTC).",
"example": "2026-10-12T09:30:00Z"
}
}
}
}
}
}
]
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
4051API_ERRORThe request failed; the printed error message has details.
42950RATE_LIMITEDToo many requests. Retryable — the CLI reports the server-provided delay.
500, 50340API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: listcustommetrics