Skip to main content

update-custom-metric

dci update-custom-metric [body] [flags]

Changes the fields in the body and leaves the others as they are (JSON Merge Patch, RFC 7396). Requires the analytics:calculatedMetrics entitlement and a metrics write permission, and the caller must own the metric, be an editor of it, or the metric must be editable by everyone. Send the metric's etag in If-Match.

  • A field you leave out is not changed.
  • variables replaces the whole list, and the letters follow the new order. The formula must still name only defined letters, so send formula too when the number or order of variables changes.
  • decimals sets both bounds: send min and max together. decimals: null removes the display precision.
  • Every other field rejects null. Send description: "" to clear the description.

With dryRun=true, the response is the metric as it would be after the update, and nothing is written.

Errors (RFC 9457 Problem Details, code field):

  • 400 validation_failed: an empty body, or the updated metric breaks a rule. details uses the same field paths and issue values as createCustomMetric.
  • 400 idempotency_key_required: no Idempotency-Key header.
  • 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 analytics.custom_metric_not_owner: the caller may not edit this metric.
  • 403 forbidden: no metrics write permission, a read-only token, or an X-Tenant-Id that the credential cannot access.
  • 404 not_found: no custom metric with this id for the customer.
  • 409 analytics.custom_metric_modified: another request changed the metric while this one was running. Retryable: read the metric again, then retry.
  • 409 idempotency_request_in_progress: a request with the same Idempotency-Key is still running. Retry with backoff.
  • 412 precondition_failed: If-Match does not match the current etag. Read the metric again, then retry.
  • 422 idempotency_key_reused: the Idempotency-Key was used with a different body.
  • 428 precondition_required: no If-Match header.
  • 503 service_unavailable: the customer's extended metrics could not be checked, or an extended key is missing while part of the data that decides the list could not be read. The key is not rejected: retry after Retry-After seconds.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Request​

Content-Type: application/merge-patch+json

FieldTypeRequiredDescription
namestringName of the metric. It must contain a character other than a space. It is stored and returned exactly as sent, without trimming.
descriptionstringDescription of the metric. Send "" to clear it.
variablesarray of objectThe variables. Their order sets their letters: the first is A, the second B, up to E. Do not send letter.
variables[].metricobjectyesThe 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.
variables[].metric.typestringyesbasic for a cost, usage or savings metric. extended for an extended metric, such as a DataHub or GenAI metric. One of: "basic", "extended".
variables[].metric.valuestringyesFor 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.
variables[].allocationIdstringyesIdentifier of a single allocation (allocationType: single in GET /analytics/v1/allocations). A group allocation is rejected. A preset allocation needs the preset allocations entitlement.
formulastringArithmetic over the variable letters. Allowed: the letters of the defined variables (A to E), numbers such as 100 or 0.5, the operators +, -, * and /, parentheses and spaces. Spaces are ignored when the formula is checked and evaluated, but the formula is stored and returned exactly as sent: A / B stays A / B. A minus can be unary (-A, A*-B). Rejected with issue: invalid_formula: a formula that starts with +, * or /, ends with an operator, has two binary operators in a row, has empty or unbalanced parentheses, or divides by a literal 0. Rejected with issue: unknown_variable: a letter with no variable, such as C when there are two variables. A variable that the formula does not use is allowed.
unitTypestringHow reports show the value: a plain number, a percentage, or a currency amount in the customer's currency. One of: "number", "percentage", "currency". Default: "number".
decimalsobjectNew display precision, with both bounds. null removes it.
decimals.minintegeryesFewest decimal places shown. Not greater than max.
decimals.maxintegeryesMost decimal places shown. Not less than min.
Raw JSON schema
{
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"description": "Request body to update a metric (JSON Merge Patch). Send at least one field. Only `decimals` accepts `null`.",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"pattern": "\\S",
"description": "Name of the metric. It must contain a character other than a space. It is stored and returned exactly as sent, without trimming.",
"example": "Cost per ride"
},
"description": {
"type": "string",
"description": "Description of the metric. Send `\"\"` to clear it.",
"example": "Total cost divided by completed rides"
},
"variables": {
"type": "array",
"description": "The variables. Their order sets their letters: the first is `A`, the second `B`, up to `E`. Do not send `letter`.",
"minItems": 1,
"maxItems": 5,
"items": {
"type": "object",
"additionalProperties": false,
"description": "One variable of a metric, as sent.",
"required": [
"metric",
"allocationId"
],
"properties": {
"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",
"pattern": "^[A-Za-z0-9_-]{1,128}$",
"description": "Identifier of a single allocation (`allocationType: single` in `GET /analytics/v1/allocations`). A group allocation is rejected. A preset allocation needs the preset allocations entitlement.",
"example": "aL1oC9tR2iDe5Kq7Zw3x"
}
}
},
"example": [
{
"metric": {
"type": "basic",
"value": "cost"
},
"allocationId": "aL1oC9tR2iDe5Kq7Zw3x"
},
{
"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": "New display precision, with both bounds. `null` removes it.",
"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": 3
}
}
}
}

Flags​

FlagTypeDefaultExampleDescription
--dry-runbooleanfalseIf true, validates the request and returns the would-be result without applying it. The response then carries the X-Dry-Run header.

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

Output​

The updated metric, or with dryRun=true the metric as it would be.

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

FieldTypeDescription
idstringIdentifier of the metric. Reports use it in metric: \{type: custom, value: &lt;id&gt;\}.
etagstringStrong entity tag, the same value as the ETag header. It changes on every update. Send it in If-Match.
namestringName of the metric, exactly as sent. It is not trimmed.
descriptionstringDescription of the metric, exactly as sent. An empty string when there is none.
ownerstring (email)Email of the owner.
variablesarray of objectThe variables, in letter order. The first is A.
variables[].letterstringLetter of the variable in the formula, from its position: A for the first, up to E.
variables[].metricobjectThe 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.
variables[].metric.typestringbasic for a cost, usage or savings metric. extended for an extended metric, such as a DataHub or GenAI metric. One of: "basic", "extended".
variables[].metric.valuestringFor 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: &lt;key&gt;\}. Any other key returns issue: extended_metric_not_found.
variables[].allocationIdstringIdentifier of the single allocation the variable measures.
formulastringArithmetic over the variable letters. Allowed: the letters of the defined variables (A to E), numbers such as 100 or 0.5, the operators +, -, * and /, parentheses and spaces. Spaces are ignored when the formula is checked and evaluated, but the formula is stored and returned exactly as sent: A / B stays A / B. A minus can be unary (-A, A*-B). Rejected with issue: invalid_formula: a formula that starts with +, * or /, ends with an operator, has two binary operators in a row, has empty or unbalanced parentheses, or divides by a literal 0. Rejected with issue: unknown_variable: a letter with no variable, such as C when there are two variables. A variable that the formula does not use is allowed.
unitTypestringHow reports show the value: a plain number, a percentage, or a currency amount in the customer's currency. One of: "number", "percentage", "currency". Default: "number".
decimalsobjectDisplay 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.
decimals.minintegerFewest decimal places shown. Not greater than max.
decimals.maxintegerMost decimal places shown. Not less than min.
createTimestring (date-time)When the metric was created (RFC 3339, UTC).
updateTimestring (date-time)When the metric was last changed (RFC 3339, UTC).

Example response (--output json)​

{
"id": "m8Tq2LxV4cRn7YpB1sKd",
"etag": "\"4d81b0c6e29a\"",
"name": "Cost per completed 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-14T16:05:00Z"
}
Raw JSON schema
{
"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
400, 42230VALIDATION_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.
40420RESOURCE_NOT_FOUNDThe requested resource does not exist. Check the identifier argument.
405, 412, 415, 4281API_ERRORThe request failed; the printed error message has details.
40921RESOURCE_CONFLICTThe operation conflicts with the resource's current state.
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: updatecustommetric