> ## Documentation Index > Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Metrics Catalog > Metric names and label values actually recorded for this org in the recent past. Use it to populate a metric picker: `GET /orgs/{org_id}/metrics` requires a name, and alarms reference names that only exist once something has emitted them. `origin` separates the two kinds: `system` metrics (`app.*`, `deployment.*`, `org.*`) are emitted by the platform and have no configuration, while `custom` ones come from a metric definition — see `definition_ids` for the config behind them. This reports what is *flowing*, not what is configured, so the two can disagree in both directions: a definition that has never matched a span will not appear, and a deleted definition's series stays until its bins age out. Needs `analytics.read` for the org-wide catalog. Passing `project_id` narrows it to series carrying that project's dimension and accepts `projects.alarms.read` there instead, so a project-scoped role gets a working metric picker. That view omits series with no project dimension, `org.credits.*` among them — which are org-level metrics that caller cannot alarm on anyway. ## OpenAPI ````yaml GET /orgs/{org_id}/metrics/catalog openapi: 3.1.0 info: title: Timbal Platform API description: Public API documentation for the Timbal platform license: name: '' version: 2.0.0 servers: - url: https://api.timbal.ai description: Production - url: https://api.dev.timbal.ai description: Development security: [] tags: - name: ace description: Action Control Engine (ACE) operations - name: alarms description: Metric series and threshold alarms - name: analytics description: Org and project analytics - name: billing description: Subscriptions, usage, and payment-related operations - name: channels description: Delivery channels alarms notify through - name: content description: Re-sign stored content URLs - name: files description: File operations - name: iam description: IAM — actions, roles, users, and authorization introspection - name: k2 description: Knowledge Bases v2 operations - name: orgs description: Organization operations - name: projects description: Project operations - name: runs description: Execution operations - name: templates description: Public project template catalog - name: users description: Authenticated user profile paths: /orgs/{org_id}/metrics/catalog: get: tags: - alarms summary: List observed metrics description: >- Metric names and label values actually recorded for this org in the recent past. Use it to populate a metric picker: `GET /orgs/{org_id}/metrics` requires a name, and alarms reference names that only exist once something has emitted them. `origin` separates the two kinds: `system` metrics (`app.*`, `deployment.*`, `org.*`) are emitted by the platform and have no configuration, while `custom` ones come from a metric definition — see `definition_ids` for the config behind them. This reports what is *flowing*, not what is configured, so the two can disagree in both directions: a definition that has never matched a span will not appear, and a deleted definition's series stays until its bins age out. Needs `analytics.read` for the org-wide catalog. Passing `project_id` narrows it to series carrying that project's dimension and accepts `projects.alarms.read` there instead, so a project-scoped role gets a working metric picker. That view omits series with no project dimension, `org.credits.*` among them — which are org-level metrics that caller cannot alarm on anyway. operationId: get_org_metrics_catalog parameters: - name: org_id in: path required: true schema: type: string - name: hours in: query description: How far back to look for observed metrics. Default 24, max 720. required: false schema: type: - integer - 'null' format: int64 - name: project_id in: query description: |- Only metrics carrying this project's dimension. Also lowers the permission needed from `analytics.read` to `projects.alarms.read` on this project. required: false schema: type: - string - 'null' responses: '200': description: Observed metrics content: application/json: schema: $ref: '#/components/schemas/OrgMetricsCatalogResBody' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - bearer_auth: [] components: schemas: OrgMetricsCatalogResBody: type: object title: OrgMetricsCatalogResponse description: Wrapper for **GET** `/orgs/{org_id}/metrics/catalog`. required: - hours - metrics properties: hours: type: integer format: int64 metrics: type: array items: $ref: '#/components/schemas/MetricCatalogEntry' ErrorMessage: type: object required: - code - message properties: code: type: string description: Machine-readable error code (e.g. `ALREADY_EXISTS`, `BAD_REQUEST`). message: type: string description: Human-readable description. MetricCatalogEntry: type: object description: One metric name observed in the window, with the labels seen under it. required: - name - origin - definition_ids - labels - label_count - observations - last_seen properties: definition_ids: type: array items: type: integer format: int64 description: |- Definitions feeding this series, for linking a custom metric to the config behind it. Empty for system metrics, and for a custom series whose definition was deleted while its bins age out. label_count: type: integer format: int64 description: |- Distinct labels observed, even when `labels` was truncated. A number far above the cap means a filter is minting labels from something unbounded. labels: type: array items: type: string description: |- Distinct `label` values observed, capped — see `label_count` for the true total. Empty for metrics that don't use the label dimension. last_seen: type: integer format: int64 description: Most recent bin (epoch milliseconds). name: type: string observations: type: integer format: int64 description: Observations recorded in the window. origin: $ref: '#/components/schemas/MetricOrigin' description: '`system` for platform series, `custom` for org-defined ones.' MetricOrigin: type: string description: >- Who defines a metric series. The distinction the API cares about is editability, not data source: system series are emitted by the crons and probes and have no configuration to show, custom ones are backed by a definition the org can change. enum: - system - custom securitySchemes: bearer_auth: type: http scheme: bearer description: >- Timbal API key. Obtain your API key from the Timbal platform settings. See [Authentication](/api-reference/authentication) for more information. ````