---
title: "Get Unified Metric Catalog"
method: GET
path: "/api/v1/metrics/catalog"
tags: ["metrics"]
---

# Get Unified Metric Catalog

`GET /api/v1/metrics/catalog`

Return every metric the caller may query, in one unified shape (PR 31).

``q`` narrows the list (Agent-Native PR 4). It exists to make REUSE cheaper than
creation: without a search, a caller weighing "do we already have something like
average handling time?" must pull ~75 entries and match by hand, so the cheapest
path is always to author a near-duplicate — and metric proliferation is exactly
what destroys one-definition-per-number.

## Query parameters

- `include_operator` boolean
- `q` string, nullable — Case-insensitive substring over label and description. Ask this BEFORE authoring a new metric — reusing an existing one keeps every number on one definition. Matches also carry usage_count.

## Response `200`

Successful Response

- UnifiedMetricCatalogResponse — GET /metrics/catalog -- every queryable metric in one flat list (PR 31).
  - `metrics` UnifiedMetricCatalogEntry[], required
    - `source_kind` 'standard' | 'platform_calculation' | 'evaluated' | 'calculated', required
    - `ref` string, required
    - `label` string, required
    - `description` string, required
    - `kind` 'measure' | 'ratio' | 'expression' | 'evaluated', required
    - `entity` string, nullable
    - `unit` UnitSpecOutput — A unit as a ``dimension → exponent`` vector plus an optional currency code. ``currency_code`` is meaningful only when a ``currency`` dimension is present. Two DIFFERENT codes are incompatible, and ``currency_code=None`` (unknown / resolved per query scope) is incompatible with EVERY coded currency — the mechanism that blocks summing an unknown-currency value into a known one (PR 14 leans on it).
      - `dimensions` object
      - `currency_code` string, nullable
      - `display_label` string, required — ``to_display_label()``, serialized (Agent-Native PR 12). Every surface that shows a raw value needs to say what unit it is IN — the audit panel prints an exact ``12,150`` directly beneath a formatted ``3.4 h``, and unlabelled that reads as hours and is wrong by a factor of 3,600. The renderer already exists here; exposing it means the client, the agent tools and the disclosures all say ``conversations · seconds`` rather than each inventing a name for the same vector from raw dimension keys.
    - `format` string, nullable
    - `time_dimension` string, nullable
    - `calculation_kind` string, nullable
    - `polarity` 'higher_is_better' | 'lower_is_better' | 'neutral', nullable
    - `status` string
    - `superseded_by` string, nullable
    - `compatibility` MetricCompatibility — How a catalog metric may combine and group (PR 23 summary).
      - `unit` UnitSpecOutput, required — A unit as a ``dimension → exponent`` vector plus an optional currency code. ``currency_code`` is meaningful only when a ``currency`` dimension is present. Two DIFFERENT codes are incompatible, and ``currency_code=None`` (unknown / resolved per query scope) is incompatible with EVERY coded currency — the mechanism that blocks summing an unknown-currency value into a known one (PR 14 leans on it).
        - `dimensions` object
        - `currency_code` string, nullable
        - `display_label` string, required — ``to_display_label()``, serialized (Agent-Native PR 12). Every surface that shows a raw value needs to say what unit it is IN — the audit panel prints an exact ``12,150`` directly beneath a formatted ``3.4 h``, and unlabelled that reads as hours and is wrong by a factor of 3,600. The renderer already exists here; exposing it means the client, the agent tools and the disclosures all say ``conversations · seconds`` rather than each inventing a name for the same vector from raw dimension keys.
      - `aggregation_behavior` string, required
      - `allowed_dimensions` string[]
    - `channels` string, nullable
    - `sources` string[]
    - `response_type` string, nullable
    - `count_shaped` boolean, nullable
    - `precision` integer, nullable
    - `percent_stored_as` string, nullable
    - `display_expression` string, nullable
    - `component_of` string[]
    - `usage_count` integer, nullable

## Other responses

- `401` — Authentication required
- `422` — Validation Error

---

[API](https://skmtc.dev/getanana/apis/cleon-api.md) · [All operations](https://skmtc.dev/getanana/apis/cleon-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getanana/cleon-api/revisions/c0f54348e251/schema)