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 asmaxResultsover 500 or an unknownsortByvalue.400 filter_key_not_supported: afilterkey other thannameorowner. Thedetailsentry lists the supported keys insupportedKeys.400 pagination_token_invalid: see above.400 tenant_id_required: a caller with access to more than one customer sent noX-Tenant-Id.403 analytics.feature_not_entitled: the customer does not have the calculated metrics entitlement.403 forbidden: no metrics read permission, or anX-Tenant-Idthat the credential cannot access.
maxResults is at most 500. A larger value returns 400 validation_failed.
sortOrder defaults to desc.
Flags
| Flag | Type | Default | Example | Description |
|---|---|---|---|---|
--max-results | integer (int64) | 50 | The maximum number of results to return in a single page. Use the page tokens to iterate through the entire collection. | |
--page-token | string | Page token, returned by a previous call, to request the next page of results | ||
--name-contains | string | monthly spend | Case-insensitive substring match against the resource name. Combined with the "filter" parameter using AND semantics. | |
--filter | string | owner:finops%40example.com | Filter 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-by | string | "update_time" | update_time | Field to sort by. Ties break by id, so paging never repeats or skips a metric. One of: "name", "create_time", "update_time". |
--sort-order | string | Specifies 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.
| Field | Type | Description |
|---|---|---|
items | array of any | Resource instances in the current page. Per-resource schemas replace items[] with array<ResourceType>. |
pageToken | string | Opaque 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. |
rowCount | integer (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",
"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",
"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.",
},
"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 status | Exit code | Error code | Meaning |
|---|---|---|---|
| 400 | 30 | VALIDATION_ERROR | The arguments or request body were rejected. Review the command's flags and payload. |
| 401 | 10 | AUTHENTICATION_FAILED | Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY. |
| 403 | 11 | PERMISSION_DENIED | The DoiT user or the active customer context does not have access. |
| 405 | 1 | API_ERROR | The request failed; the printed error message has details. |
| 429 | 50 | RATE_LIMITED | Too many requests. Retryable — the CLI reports the server-provided delay. |
| 500, 503 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |
Related
- create-custom-metric — Create a custom metric
- delete-custom-metric — Delete a custom metric
- get-custom-metric — Get a custom metric
- update-custom-metric — Update a custom metric
- API reference: GET /analytics/v1/custom-metrics
Aliases: listcustommetrics