Metrics List and Detail

The metrics routes expose searchable metric registry data for an organization. They are read-only and API-key authenticated. Use them to discover metrics, select a metric ID, and read the broader metric detail envelope before fetching the agent-facing contract.

Both routes request metrics:read internally. Current Agent Contract keys satisfy that request through the compatibility layer, and older metrics:read keys remain compatible.

These routes mirror the Metric Registry discovery surface: search, filters, lifecycle status, owner context, policy tier, version context, and enough detail to decide whether a candidate metric should be inspected through the contract route.

Read the Metric Registry docs

List metrics

GET https://app.clarilayer.com/api/v1/metrics?page=1&pageSize=20
Authorization: Bearer cl_0000000000000000000000000000000000000000
Accept: application/json

Query parameters

q

Search string. When present, the route uses search behavior instead of the plain list behavior. Whitespace-only values are ignored.

page

Positive integer page number. Invalid or missing values default to 1.

pageSize

Positive integer page size. Invalid or missing values default to 20; values above 100 are capped at 100.

lifecycle_status

Canonical lifecycle filter. When present, it is passed through as the effective lifecycle filter.

status

Legacy status filter. Used only when lifecycle_status is absent. The compatibility mapping is draft -> DRAFT, review -> VALIDATED,CANDIDATE, approved -> APPROVED,RELEASED, and deprecated -> DEPRECATED.

policy_tier

Policy-tier filter. Current responses use policy_tier; the old tier query parameter is not translated by this route.

scope

Governance-scope filter. Valid values are enterprise_canonical, domain_canonical, and exploratory. Invalid scope values are ignored.

type

Metric type filter, such as base or derived.

Response

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000011",
      "name": "Monthly Revenue",
      "description": "Total revenue per month.",
      "policy_tier": "Financial",
      "owner_team": "Finance",
      "status": "approved",
      "lifecycle_status": "RELEASED",
      "definition_version": "2.0.0",
      "scope": "enterprise_canonical",
      "domain_id": null,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-05-01T00:00:00.000Z",
      "concept_name": "Revenue",
      "template_name": "Revenue Template"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 1,
    "totalPages": 1
  },
  "meta": { "apiVersion": "v1" }
}

The status field is retained for legacy v1 consumers. New consumers should prefer lifecycle_status.

Search example

GET https://app.clarilayer.com/api/v1/metrics?q=monthly%20revenue&policy_tier=Financial&page=1&pageSize=20
Authorization: Bearer cl_0000000000000000000000000000000000000000

Search responses use the same envelope as list responses.

Get metric detail

GET https://app.clarilayer.com/api/v1/metrics/5e6f7a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b
Authorization: Bearer cl_0000000000000000000000000000000000000000
Accept: application/json

Metric IDs must be UUIDs. Invalid UUID shape returns 400. If the metric is missing or belongs to another organization, the route returns 404.

Detail response shape

The detail route returns a single-resource envelope:

{
  "data": {
    "metric": {
      "id": "5e6f7a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
      "org_id": "22222222-2222-4222-8222-222222222222",
      "project_id": "33333333-3333-4333-8333-333333333333",
      "metric_type": "base",
      "key": "monthly_revenue",
      "name": "Monthly Revenue",
      "description": "Total recognized revenue for the month.",
      "definition_version": "2.0.0",
      "status": "approved",
      "policy_tier": "Financial",
      "owner_team": "Finance",
      "owner_display_name": null,
      "tags": ["revenue"],
      "concept_name": "Revenue",
      "template_name": "Revenue Template",
      "sql_expression": "SELECT SUM(amount) FROM fact_invoices",
      "grains": ["month"],
      "default_grain": "month",
      "dimensions": [],
      "filters": ["status = 'recognized'"],
      "source_refs": [{ "table": "fact_invoices" }],
      "expression": null,
      "dependencies": null,
      "lifecycle_status": "RELEASED",
      "scope": "enterprise_canonical",
      "domain_id": null,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-05-01T00:00:00.000Z"
    },
    "relationships": [],
    "approvals": [],
    "versionHistory": [],
    "fiscal_calendar_start_month": 1,
    "time_semantics": null,
    "deprecated_framing_rules": [],
    "dimension_map": {},
    "column_aliases": {},
    "execution_context": {
      "resolved_parameters": {},
      "rendered_sql_examples": [],
      "latest_closed_period": null
    },
    "governance_facts": {
      "owner_team": null,
      "approver_role": null,
      "approver_user": null,
      "approved_at": null,
      "lifecycle_status": null,
      "current_version": null,
      "effective_from": null,
      "effective_to": null,
      "next_review_date": null
    },
    "approval_state": null,
    "consumer_contexts": {},
    "requires_disambiguation": null,
    "policy_examples": []
  },
  "meta": { "apiVersion": "v1" }
}

The example is intentionally compact and uses sample values. Live metrics can include populated relationships, approvals, version history, time semantics, disambiguation directives, consumer contexts, deprecated framing rules, execution examples, and policy examples.

Field notes

metric.org_id is present on the detail response. Consumers should not treat it as an authorization primitive; the route already enforces org ownership before returning data.

definition_version is the current v1 field name for the metric definition version. Avoid using older version assumptions for the metric object.

policy_tier is the current field name for governance tier. Avoid older tier assumptions.

fiscal_calendar_start_month is the organization-default fiscal calendar start month, where 1 means January.

time_semantics is nullable and may contain forward-compatible keys. Consumers should read known keys without rejecting unknown keys.

approval_state, consumer_contexts, requires_disambiguation, and policy_examples are intended for consumers that need richer agent behavior. Empty objects, empty arrays, and null values are meaningful stable defaults.

Errors

Missing or invalid API key:

{ "error": "Invalid API key" }

Invalid metric ID:

{ "error": "Invalid metric ID format" }

Metric not found or outside the key's organization:

{ "error": "Metric not found" }

Server failure:

{ "error": "Failed to fetch metric" }

See also

• Authentication
• Metrics contract envelope
• Metric Registry
• AI agent context guide