create-custom-metric
dci create-custom-metric [body] [flags]
Creates a custom metric owned by the caller. Requires the
analytics:calculatedMetrics entitlement and a metrics write
permission.
Create the allocations first (POST /analytics/v1/allocations), then
reference them from variables[].allocationId. The order of
variables sets their letters: the first is A, the second B, up
to E. Write formula with those letters.
With dryRun=true, the response is 200 with the metric that would
be created. Its id, etag, createTime and updateTime are
placeholders.
Errors (RFC 9457 Problem Details, code field):
400 validation_failed: the body breaks a rule.detailsholds one entry per problem, withfieldset to a path such asvariables[1].allocationIdandissueset to one of:required: a required field is missing or blank.value_not_in_enum: a value outside its allowed set.out_of_range: a number outside its bounds, ordecimals.mingreater thandecimals.max.invalid_formula:formuladoes not parse;detailsays why.unknown_variable:formulauses a letter with no variable.allocation_not_found: no allocation with this id for the customer.allocation_not_single: the id names a group allocation.allocation_not_available: a preset allocation the customer is not entitled to.extended_metric_not_found: anextendedmetric key thatGET /analytics/v1/extended-metricsdoes not list with data sourcebillingorbilling-datahub.
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 forbidden: no metrics write permission, a read-only token, or anX-Tenant-Idthat the credential cannot access.409 idempotency_request_in_progress: a request with the sameIdempotency-Keyis still running. Retry with backoff.422 idempotency_key_reused: theIdempotency-Keywas used with a different body.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/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | 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. Default: "". | |
variables | array of object | yes | 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 | yes | 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 | Number of decimal places reports show, from min to max. min must not be greater than max. | |
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,
"description": "Request body to create a metric.",
"required": [
"name",
"variables",
"formula"
],
"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.",
"default": "",
"example": "Total cost divided by reported 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": {
"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
}
}
}
}
}
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
Dry-run preview: the metric that would be created. id, etag, createTime and updateTime are placeholders, and nothing was written.
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": "dryrun",
"etag": "\"dry-run\"",
"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"
}
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. |
| 405, 415 | 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
- delete-custom-metric — Delete a custom metric
- get-custom-metric — Get a custom metric
- list-custom-metrics — List custom metrics
- update-custom-metric — Update a custom metric
- API reference: POST /analytics/v1/custom-metrics
Aliases: createcustommetric