Skip to main content

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. details holds one entry per problem, with field set to a path such as variables[1].allocationId and issue set 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, or decimals.min greater than decimals.max.
    • invalid_formula: formula does not parse; detail says why.
    • unknown_variable: formula uses 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: an extended metric key that GET /analytics/v1/extended-metrics does not list with data source billing or billing-datahub.
  • 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 forbidden: no metrics write permission, a read-only token, or an X-Tenant-Id that the credential cannot access.
  • 409 idempotency_request_in_progress: a request with the same Idempotency-Key is still running. Retry with backoff.
  • 422 idempotency_key_reused: the Idempotency-Key was used with a different body.
  • 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/json

FieldTypeRequiredDescription
namestringyesName 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. Default: "".
variablesarray of objectyesThe 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.
formulastringyesArithmetic 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".
decimalsobjectNumber of decimal places reports show, from min to max. min must not be greater than max.
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,
"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​

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​

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.

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": "dryrun",
"etag": "\"dry-run\"",
"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"
}
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.
405, 4151API_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: createcustommetric