---
title: "Get Metric Usage"
method: GET
path: "/api/v1/metrics/{source}/{ref}/usage"
tags: ["metrics"]
---

# Get Metric Usage

`GET /api/v1/metrics/{source}/{ref}/usage`

Where a metric is used (widgets, PR 37) + its calculation lineage (PR 18).

## Path parameters

- `source` string, required
- `ref` string, required

## Response `200`

Successful Response

- MetricUsage — GET /metrics/{source}/{ref}/usage -- where a metric is used, and its calculation lineage (PR 38). ``used_in`` is widget USAGE (PR 37's projection); ``depends_on`` / ``dependents`` are CALCULATION edges (PR 18's active projection). ``circular`` flags a metric caught in a dependency cycle -- writes are guarded so it is normally false, surfaced defensively.
  - `ref` string, required
  - `used_in` MetricUsageRef[]
    - `widget_id` string, required
    - `dashboard_id` string, required
    - `widget_title` string, nullable
  - `depends_on` MetricRelation[]
    - `source` 'standard' | 'platform_calculation' | 'evaluated' | 'calculated', required
    - `ref` string, required
    - `label` string, nullable
  - `dependents` MetricRelation[]
    - `source` 'standard' | 'platform_calculation' | 'evaluated' | 'calculated', required
    - `ref` string, required
    - `label` string, nullable
  - `circular` boolean

## Other responses

- `401` — Tenant not identified
- `403` — Caller may not query this metric
- `404` — Unknown source or metric
- `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)