---
title: "GET /v1/metrics/{metricId}"
method: GET
path: "/v1/metrics/{metricId}"
tags: ["metrics"]
---

# GET /v1/metrics/{metricId}

`GET /v1/metrics/{metricId}`

## Request

- Base URL: `https://help.steep.app` (the document declares no server; this is the origin it was published from)
- URL: `https://help.steep.app/v1/metrics/{metricId}`
- Auth: none declared

Get a single metric by `id`. A metric or dimension may carry the data team's AI context. `synonyms`: Other names people use for this, e.g. abbreviations or terms in other languages. `examples` (metrics only): Sample questions this metric answers. `agentInstructions`: The data team's guidance for AI agents on using this. Follow it whenever this is part of what you query or present.

## Path parameters

- `metricId` string, required: `metric.id` — Unique resource ID (opaque).

## Query parameters

- `expand` string, boolean: Boolean string. When `true`, populates `dimensions`, `module`, `slices`, `cohort`, `owners`, `category`, `filters`, and `teamIdsWithAccess`. When `false`, those fields are `null`.

## Response `200`

Response for status 200

- union
  - object
    - `id` string, required: Unique resource ID (opaque).
    - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
    - `label` string, required
    - `description` unknown, required
    - `link` string, required: A link to the metric in the app
    - `isPrivate` boolean, required
    - `teamIdsWithAccess` string[], required: Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`.
    - `isUnlisted` boolean, required
    - `updatedAt` string, date-time, required
    - `dimensions` object[], required: Dimensions for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `type` 'string-or-boolean' | 'city' | 'country' | 'time' | 'h3-cell-index', required
      - `description` unknown, required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `module` object, required: Module for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `description` unknown, required
      - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
      - `table` string, required
      - `schema` string, required
      - `externalSource` 'dbt-cloud' | 'cube' | 'code', required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `slices` object[], required: Slices for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` string, required
      - `description` unknown
      - `filter` object, required
        - `column` string, required
        - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
        - `expression` string, required
    - `cohort` object, required: Cohort for this metric. Populated when `expand=true`; otherwise `null`.
      - `deltaTimeCalculationType` union, required
        - string
        - string
      - `label` unknown
      - `calculateRetention` unknown
      - `timeGrains` string[]
      - `time` string, required
    - `owners` string[], required: Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`.
    - `category` unknown, required
    - `time` unknown, required
    - `timeResampling` 'sum/divide' | 'average/repeat', required
    - `timeGrains` string[], required
    - `filters` object[], required: Filters for this metric. Populated when `expand=true`; otherwise `null`.
      - `column` string, required
      - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
      - `expression` string, required
    - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
    - `examples` string[], required: Sample questions this metric answers.
    - `agentInstructions` unknown, required
    - `calculation` string, required
    - `value` string, required
  - object
    - `id` string, required: Unique resource ID (opaque).
    - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
    - `label` string, required
    - `description` unknown, required
    - `link` string, required: A link to the metric in the app
    - `isPrivate` boolean, required
    - `teamIdsWithAccess` string[], required: Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`.
    - `isUnlisted` boolean, required
    - `updatedAt` string, date-time, required
    - `dimensions` object[], required: Dimensions for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `type` 'string-or-boolean' | 'city' | 'country' | 'time' | 'h3-cell-index', required
      - `description` unknown, required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `module` object, required: Module for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `description` unknown, required
      - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
      - `table` string, required
      - `schema` string, required
      - `externalSource` 'dbt-cloud' | 'cube' | 'code', required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `slices` object[], required: Slices for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` string, required
      - `description` unknown
      - `filter` object, required
        - `column` string, required
        - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
        - `expression` string, required
    - `cohort` object, required: Cohort for this metric. Populated when `expand=true`; otherwise `null`.
      - `deltaTimeCalculationType` union, required
        - string
        - string
      - `label` unknown
      - `calculateRetention` unknown
      - `timeGrains` string[]
      - `time` string, required
    - `owners` string[], required: Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`.
    - `category` unknown, required
    - `time` unknown, required
    - `timeResampling` 'sum/divide' | 'average/repeat', required
    - `timeGrains` string[], required
    - `filters` object[], required: Filters for this metric. Populated when `expand=true`; otherwise `null`.
      - `column` string, required
      - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
      - `expression` string, required
    - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
    - `examples` string[], required: Sample questions this metric answers.
    - `agentInstructions` unknown, required
    - `calculation` string, required
    - `numerator` unknown, required
    - `denominator` unknown, required
    - `format` 'number' | 'percentage', required
  - object
    - `id` string, required: Unique resource ID (opaque).
    - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
    - `label` string, required
    - `description` unknown, required
    - `link` string, required: A link to the metric in the app
    - `isPrivate` boolean, required
    - `teamIdsWithAccess` string[], required: Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`.
    - `isUnlisted` boolean, required
    - `updatedAt` string, date-time, required
    - `dimensions` object[], required: Dimensions for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `type` 'string-or-boolean' | 'city' | 'country' | 'time' | 'h3-cell-index', required
      - `description` unknown, required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `module` object, required: Module for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `description` unknown, required
      - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
      - `table` string, required
      - `schema` string, required
      - `externalSource` 'dbt-cloud' | 'cube' | 'code', required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `slices` object[], required: Slices for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` string, required
      - `description` unknown
      - `filter` object, required
        - `column` string, required
        - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
        - `expression` string, required
    - `cohort` object, required: Cohort for this metric. Populated when `expand=true`; otherwise `null`.
      - `deltaTimeCalculationType` union, required
        - string
        - string
      - `label` unknown
      - `calculateRetention` unknown
      - `timeGrains` string[]
      - `time` string, required
    - `owners` string[], required: Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`.
    - `category` unknown, required
    - `time` unknown, required
    - `timeResampling` 'sum/divide' | 'average/repeat', required
    - `timeGrains` string[], required
    - `filters` object[], required: Filters for this metric. Populated when `expand=true`; otherwise `null`.
      - `column` string, required
      - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
      - `expression` string, required
    - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
    - `examples` string[], required: Sample questions this metric answers.
    - `agentInstructions` unknown, required
    - `calculation` string, required
  - object
    - `id` string, required: Unique resource ID (opaque).
    - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
    - `label` string, required
    - `description` unknown, required
    - `link` string, required: A link to the metric in the app
    - `isPrivate` boolean, required
    - `teamIdsWithAccess` string[], required: Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`.
    - `isUnlisted` boolean, required
    - `updatedAt` string, date-time, required
    - `dimensions` object[], required: Dimensions for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `type` 'string-or-boolean' | 'city' | 'country' | 'time' | 'h3-cell-index', required
      - `description` unknown, required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `module` object, required: Module for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `description` unknown, required
      - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
      - `table` string, required
      - `schema` string, required
      - `externalSource` 'dbt-cloud' | 'cube' | 'code', required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `slices` object[], required: Slices for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` string, required
      - `description` unknown
      - `filter` object, required
        - `column` string, required
        - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
        - `expression` string, required
    - `cohort` object, required: Cohort for this metric. Populated when `expand=true`; otherwise `null`.
      - `deltaTimeCalculationType` union, required
        - string
        - string
      - `label` unknown
      - `calculateRetention` unknown
      - `timeGrains` string[]
      - `time` string, required
    - `owners` string[], required: Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`.
    - `category` unknown, required
    - `time` unknown, required
    - `timeResampling` 'sum/divide' | 'average/repeat', required
    - `timeGrains` string[], required
    - `filters` object[], required: Filters for this metric. Populated when `expand=true`; otherwise `null`.
      - `column` string, required
      - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
      - `expression` string, required
    - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
    - `examples` string[], required: Sample questions this metric answers.
    - `agentInstructions` unknown, required
    - `calculation` string, required
    - `distinct_on` string, required
  - object
    - `id` string, required: Unique resource ID (opaque).
    - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
    - `label` string, required
    - `description` unknown, required
    - `link` string, required: A link to the metric in the app
    - `isPrivate` boolean, required
    - `teamIdsWithAccess` string[], required: Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`.
    - `isUnlisted` boolean, required
    - `updatedAt` string, date-time, required
    - `dimensions` object[], required: Dimensions for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `type` 'string-or-boolean' | 'city' | 'country' | 'time' | 'h3-cell-index', required
      - `description` unknown, required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `module` object, required: Module for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `description` unknown, required
      - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
      - `table` string, required
      - `schema` string, required
      - `externalSource` 'dbt-cloud' | 'cube' | 'code', required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `slices` object[], required: Slices for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` string, required
      - `description` unknown
      - `filter` object, required
        - `column` string, required
        - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
        - `expression` string, required
    - `cohort` object, required: Cohort for this metric. Populated when `expand=true`; otherwise `null`.
      - `deltaTimeCalculationType` union, required
        - string
        - string
      - `label` unknown
      - `calculateRetention` unknown
      - `timeGrains` string[]
      - `time` string, required
    - `owners` string[], required: Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`.
    - `category` unknown, required
    - `time` unknown, required
    - `timeResampling` 'sum/divide' | 'average/repeat', required
    - `timeGrains` string[], required
    - `filters` object[], required: Filters for this metric. Populated when `expand=true`; otherwise `null`.
      - `column` string, required
      - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
      - `expression` string, required
    - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
    - `examples` string[], required: Sample questions this metric answers.
    - `agentInstructions` unknown, required
    - `calculation` string, required
    - `sqlExpression` string, required
  - object
    - `id` string, required: Unique resource ID (opaque).
    - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
    - `label` string, required
    - `description` unknown, required
    - `link` string, required: A link to the metric in the app
    - `isPrivate` boolean, required
    - `teamIdsWithAccess` string[], required: Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`.
    - `isUnlisted` boolean, required
    - `updatedAt` string, date-time, required
    - `dimensions` object[], required: Dimensions for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `type` 'string-or-boolean' | 'city' | 'country' | 'time' | 'h3-cell-index', required
      - `description` unknown, required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `module` object, required: Module for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `description` unknown, required
      - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
      - `table` string, required
      - `schema` string, required
      - `externalSource` 'dbt-cloud' | 'cube' | 'code', required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `slices` object[], required: Slices for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` string, required
      - `description` unknown
      - `filter` object, required
        - `column` string, required
        - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
        - `expression` string, required
    - `cohort` object, required: Cohort for this metric. Populated when `expand=true`; otherwise `null`.
      - `deltaTimeCalculationType` union, required
        - string
        - string
      - `label` unknown
      - `calculateRetention` unknown
      - `timeGrains` string[]
      - `time` string, required
    - `owners` string[], required: Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`.
    - `category` unknown, required
    - `time` unknown, required
    - `timeResampling` 'sum/divide' | 'average/repeat', required
    - `timeGrains` string[], required
    - `filters` object[], required: Filters for this metric. Populated when `expand=true`; otherwise `null`.
      - `column` string, required
      - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
      - `expression` string, required
    - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
    - `examples` string[], required: Sample questions this metric answers.
    - `agentInstructions` unknown, required
    - `calculation` string, required
    - `numeratorSql` unknown, required
    - `denominatorSql` unknown, required
    - `format` 'number' | 'percentage', required
  - object
    - `id` string, required: Unique resource ID (opaque).
    - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
    - `label` string, required
    - `description` unknown, required
    - `link` string, required: A link to the metric in the app
    - `isPrivate` boolean, required
    - `teamIdsWithAccess` string[], required: Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`.
    - `isUnlisted` boolean, required
    - `updatedAt` string, date-time, required
    - `dimensions` object[], required: Dimensions for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `type` 'string-or-boolean' | 'city' | 'country' | 'time' | 'h3-cell-index', required
      - `description` unknown, required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `module` object, required: Module for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` unknown, required
      - `description` unknown, required
      - `identifier` string, required: Readable semantic model key. Used to cross-reference objects in the semantic model.
      - `table` string, required
      - `schema` string, required
      - `externalSource` 'dbt-cloud' | 'cube' | 'code', required
      - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
      - `agentInstructions` unknown, required
    - `slices` object[], required: Slices for this metric. Populated when `expand=true`; otherwise `null`.
      - `id` string, required: Unique resource ID (opaque).
      - `label` string, required
      - `description` unknown
      - `filter` object, required
        - `column` string, required
        - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
        - `expression` string, required
    - `cohort` object, required: Cohort for this metric. Populated when `expand=true`; otherwise `null`.
      - `deltaTimeCalculationType` union, required
        - string
        - string
      - `label` unknown
      - `calculateRetention` unknown
      - `timeGrains` string[]
      - `time` string, required
    - `owners` string[], required: Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`.
    - `category` unknown, required
    - `time` unknown, required
    - `timeResampling` 'sum/divide' | 'average/repeat', required
    - `timeGrains` string[], required
    - `filters` object[], required: Filters for this metric. Populated when `expand=true`; otherwise `null`.
      - `column` string, required
      - `operator` 'equals' | 'not-equals' | 'less-than' | 'less-than-or-equal' | 'greater-than' | 'greater-than-or-equal' | 'in' | 'not-in' | 'is' | 'is-not' | 'like' | 'not-like', required
      - `expression` string, required
    - `synonyms` string[], required: Other names people use for this, e.g. abbreviations or terms in other languages.
    - `examples` string[], required: Sample questions this metric answers.
    - `agentInstructions` unknown, required
    - `calculation` string, required
    - `numeratorMetricId` string, required: `id` of the metric used as the numerator
    - `denominatorMetricId` string, required: `id` of the metric used as the denominator
    - `format` 'number' | 'percentage', required

## Other responses

- `401`: Response for status 401
- `403`: Response for status 403
- `422`: Response for status 422
- `429`: Response for status 429
- `500`: Response for status 500

---

[API](https://skmtc.dev/steep/apis/steep-api.md) - [All operations](https://skmtc.dev/steep/apis/steep-api/llms.txt) - [OpenAPI document](https://skmtc.dev/steep/apis/steep-api/revisions/cc9677742952?raw)