Skip to main content

list-extended-metrics

dci list-extended-metrics [flags]

Returns a page of the extended metrics available to the customer: the global extended metrics the customer's plan, tenant type, clouds, integrations and data include, and the customer's DataHub metrics. Use an item's key as value in metric: \{type: extended, value: <key>\}.

Where a key is accepted depends on its dataSource: a custom metric variable takes a billing or billing-datahub key (filter with dataSource:billing,billing-datahub), and a report or alert takes a key of its own data source. A key that is not listed here gets issue: extended_metric_not_found from create and update custom metric.

Items are sorted by label, then key, then dataSource. A key appears once per data source. rowCount is the exact number of items that match filter, across all pages. The page token is opaque and bound to filter: reusing it with a different filter gets 400 pagination_token_invalid.

Errors (RFC 9457 Problem Details, code field):

  • 400 validation_failed: a bad parameter, such as maxResults over 500, or a dataSource filter value outside the data sources listed in ExtendedMetric.dataSource (issue: value_not_in_enum).
  • 400 filter_key_not_supported: a filter key other than dataSource. 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 forbidden: no metrics read permission, or an X-Tenant-Id that the credential cannot access.
  • 503 service_unavailable: the extended metrics or the customer's plan could not be read. Retry after Retry-After seconds.

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

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
--filterstringdataSource:billing,billing-datahubFilter as key:value pairs, | between keys. Keys, operand types and operators: - dataSource — one of billing, billing-datahub, bqlens, genai-collection, kubernetes-utilization and tokenomics; operator eq. Comma-separated values for OR. Any other key returns 400 filter_key_not_supported. For example dataSource:billing,billing-datahub lists the keys a custom metric variable accepts. Percent-encode ,, |, : and spaces inside values.

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

Output​

A page of extended metrics, sorted by label.

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": [
{
"key": "amortized_cost",
"label": "Amortized cost",
"dataSource": "billing"
},
{
"key": "completed_rides",
"label": "Completed rides",
"dataSource": "billing-datahub"
}
],
"rowCount": 2
}
Raw JSON schema
{
"description": "A page of extended 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": "An extended metric the customer can use: a global extended metric or one of the customer's DataHub metrics.",
"example": {
"key": "completed_rides",
"label": "Completed rides",
"dataSource": "billing-datahub"
},
"required": [
"key",
"label",
"dataSource"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "Key of the metric. Send it as `value` in `metric: {type: extended, value: <key>}`.",
"x-doit-confidentiality": "customer-data",
"example": "completed_rides"
},
"label": {
"type": "string",
"description": "Name of the metric as the DoiT console shows it.",
"x-doit-confidentiality": "customer-data",
"example": "Completed rides"
},
"dataSource": {
"type": "string",
"enum": [
"billing",
"billing-datahub",
"bqlens",
"genai-collection",
"kubernetes-utilization",
"tokenomics"
],
"description": "Data source the metric reads. A custom metric variable accepts `billing` and `billing-datahub` keys. A report or alert accepts the keys of its own `dataSource`. The customer's DataHub metrics are `billing-datahub`.",
"example": "billing"
}
}
}
}
}
}
]
}

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: listextendedmetrics