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.
variablesreplaces the whole list, and the letters follow the new order. The formula must still name only defined letters, so sendformulatoo when the number or order of variables changes.decimalssets both bounds: sendminandmaxtogether.decimals: nullremoves the display precision.- Every other field rejects
null. Senddescription: ""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.detailsuses the samefieldpaths andissuevalues ascreateCustomMetric.400 idempotency_key_required: noIdempotency-Keyheader.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 analytics.custom_metric_not_owner: the caller may not edit this metric.403 forbidden: no metrics write permission, a read-only token, or anX-Tenant-Idthat 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 sameIdempotency-Keyis still running. Retry with backoff.412 precondition_failed:If-Matchdoes not match the currentetag. Read the metric again, then retry.422 idempotency_key_reused: theIdempotency-Keywas used with a different body.428 precondition_required: noIf-Matchheader.503 service_unavailable: the customer's extended metrics could not be checked, or anextendedkey is missing while part of the data that decides the list could not be read. The key is not rejected: retry afterRetry-Afterseconds.
Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.
Request
Content-Type: application/merge-patch+json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Name of the metric. It must contain a character other than a space. It is stored and returned exactly as sent, without trimming. | |
description | string | Description of the metric. Send "" to clear it. | |
variables | array of object | The variables. Their order sets their letters: the first is A, the second B, up to E. Do not send letter. | |
variables[].metric | object | yes | 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. |
variables[].metric.type | string | yes | basic 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.value | string | yes | 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. |
variables[].allocationId | string | yes | 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. |
formula | string | Arithmetic 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. | |
unitType | string | How 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". | |
decimals | object | New display precision, with both bounds. null removes it. | |
decimals.min | integer | yes | Fewest decimal places shown. Not greater than max. |
decimals.max | integer | yes | Most 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
| Flag | Type | Default | Example | Description |
|---|---|---|---|---|
--dry-run | boolean | false | If 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.
| Field | Type | Description |
|---|---|---|
id | string | Identifier of the metric. Reports use it in metric: \{type: custom, value: <id>\}. |
etag | string | Strong entity tag, the same value as the ETag header. It changes on every update. Send it in If-Match. |
name | string | Name of the metric, exactly as sent. It is not trimmed. |
description | string | Description of the metric, exactly as sent. An empty string when there is none. |
owner | string (email) | Email of the owner. |
variables | array of object | The variables, in letter order. The first is A. |
variables[].letter | string | Letter of the variable in the formula, from its position: A for the first, up to E. |
variables[].metric | object | 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. |
variables[].metric.type | string | basic 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.value | string | 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. |
variables[].allocationId | string | Identifier of the single allocation the variable measures. |
formula | string | Arithmetic 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. |
unitType | string | How 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". |
decimals | object | 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. |
decimals.min | integer | Fewest decimal places shown. Not greater than max. |
decimals.max | integer | Most decimal places shown. Not less than min. |
createTime | string (date-time) | When the metric was created (RFC 3339, UTC). |
updateTime | string (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",
"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",
"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, 422 | 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. |
| 404 | 20 | RESOURCE_NOT_FOUND | The requested resource does not exist. Check the identifier argument. |
| 405, 412, 415, 428 | 1 | API_ERROR | The request failed; the printed error message has details. |
| 409 | 21 | RESOURCE_CONFLICT | The operation conflicts with the resource's current state. |
| 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
- list-custom-metrics — List custom metrics
- API reference: PATCH /analytics/v1/custom-metrics/{id}
Aliases: updatecustommetric