Update a custom metric

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.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required
^[A-Za-z0-9_-]{1,128}$

Identifier of the custom metric, as returned in id.

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 fields to change.

Request body to update a metric (JSON Merge Patch). Send at least one field. Only decimals accepts null.

string
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. Send "" to clear it.

variables
array of objects
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
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 | null

New display precision, with both bounds. null removes it.

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
required

The ETag of the current version, from a get, create or update response. A stale value returns 412; re-read the resource and retry with the new ETag.

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