Create a custom metric

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.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
boolean
Defaults to false

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

Body Params

The metric to create.

Request body to create a metric.

string
required
length ≥ 1
\S

Name of the metric. It must contain a character other than a space. It is stored and returned exactly as sent, without trimming.

string

Description of the metric.

variables
array of objects
required
length between 1 and 5

The variables. Their order sets their letters: the first is A, the second B, up to E. Do not send letter.

variables*

One variable of a metric, as sent.

metric
object
required

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.

string
required
^[A-Za-z0-9_-]{1,128}$

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.

string
required
length ≥ 1
^[A-E0-9+*/(). -]+$

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.

string
enum
Defaults to number

How reports show the value: a plain number, a percentage, or a currency amount in the customer's currency.

Allowed:
decimals
object

Number of decimal places reports show, from min to max. min must not be greater than max.

Headers
string
required
length between 1 and 255

Client-generated key (UUID v4 or ULID recommended). Retrying with the same key and request returns the stored response instead of repeating the operation; the key is kept for 24 hours.

string

Customer (tenant) ID for the request. This is separate from authentication: you still pass your personal or service account API token in the Authorization header (Bearer <token>). See Get Started.

When to omit (most callers): If your personal or service account token belongs to a single customer, omit this header. The API resolves that customer from the token.

When to send: If your credential can access more than one customer, set X-Tenant-Id to the customer ID you want to act on. A service account can select an active direct or nested descendant of its home customer; the endpoint's normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns 403 Forbidden. Prefer this header over the legacy customerContext query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json