---
title: "List custom metric definitions"
method: GET
path: "/orgs/{org_id}/metrics/definitions"
tags: ["alarms"]
---

# List custom metric definitions

`GET /orgs/{org_id}/metrics/definitions`

The org's custom metric definitions and their current predicates.

`project_id` filters to what is *in effect* for that project, which includes org-wide definitions (those with no `project_id`) since they run against that project's runs too.

This lists configuration, not data. A definition that has never matched a span appears here but not in `GET /orgs/{org_id}/metrics/catalog`.

Filtered per definition the same way `GET /orgs/{org_id}/alarms` is: org-wide definitions need `alarms.read`, project ones need `projects.alarms.read` on the owner. So a project-scoped caller sees their own definitions but not the org-wide ones that also run against their runs, even with `project_id` set.

## Path parameters

- `org_id` string, required

## Query parameters

- `project_id` string, nullable

## Response `200`

List of definitions

- ListMetricDefinitionsResBody — Wrapper for **GET** `/orgs/{org_id}/metrics/definitions`.
  - `definitions` MetricDefinitionOut[], required
    - `created_at` string, date-time, required
    - `enabled` boolean, required
    - `has_error` boolean, nullable
    - `id` integer, required
    - `label_source` string, required — `none` or `span_name`.
    - `metric_name` string, required
    - `min_duration_ms` integer, nullable
    - `name` string, required
    - `project_id` integer, nullable — Project scope; omitted when the filter applies to the whole org.
    - `source` 'trace_span', required — Where a definition draws its observations from. One variant today. It is in the payload from the start so that adding a second source is an additive change to this enum instead of a new resource alongside `/metrics/definitions` — the reason the endpoint is named for metrics rather than for traces.
    - `span_name` string, nullable
    - `span_name_prefix` string, nullable
    - `status_code` string, nullable
    - `value_source` string, required — `count`, `duration_ms`, or `usage:<key>`.

## Other responses

- `403` — Forbidden

## Changes

- **2026-07-28** `dd7e398ce0d3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/changes/orgs/:org_id/metrics/definitions/get.md)

---

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