Delete a custom metric

Deletes a custom metric. This cannot be undone. Requires the
analytics:calculatedMetrics entitlement and a metrics write
permission, and only the owner can delete a metric. Send the
metric's etag in If-Match.

A metric that a report or an alert uses cannot be deleted. Remove it
from them first.

A retry with the same Idempotency-Key returns the first 204. A
new request for a metric that no longer exists, including one that
is already deleted, returns 404 not_found: treat it as gone.

With dryRun=true, every check runs and nothing is deleted.

Errors (RFC 9457 Problem Details, code field):

  • 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 does not own the
    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,
    including a metric that is already deleted.
  • 409 delete_blocked_by_dependencies: reports, allocations or alerts
    use the metric. details has one entry per user, with issue
    set to used_by_report, used_by_allocation or used_by_alert,
    and resourceType and resourceId naming that user, for example
    {"issue": "used_by_report", "resourceType": "report", "resourceId": "..."}. An allocation uses the metric when one of
    its splits is weighted by it.
  • 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 for
    another request.
  • 428 precondition_required: no If-Match header.
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.

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.

Responses

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