---
title: "Query a metric series"
method: GET
path: "/orgs/{org_id}/metrics"
tags: ["alarms"]
---

# Query a metric series

`GET /orgs/{org_id}/metrics`

Time-bucketed count/sum/avg/min/max for one metric, with optional dimension filters.

Needs `analytics.read` for an unrestricted query. Passing `project_id` also accepts `projects.alarms.read` on that project, so a project-scoped role can read the series behind its own alarms.

## Path parameters

- `org_id` string, required

## Query parameters

- `name` string, required
- `period_seconds` integer, nullable
- `from` integer, nullable
- `to` integer, nullable
- `project_id` string, nullable
- `project_env_id` string, nullable
- `deployment_id` string, nullable
- `workforce_id` string, nullable
- `label` string, nullable

## Response `200`

Metric series

- OrgMetricsResBody — Wrapper for **GET** `/orgs/{org_id}/metrics`.
  - `bins` MetricBinOut[], required — Buckets with data, ascending; empty buckets are omitted.
    - `avg` number, double, nullable
    - `count` integer, required — Observations in the bucket.
    - `max` number, double, nullable
    - `min` number, double, nullable
    - `sum` number, double, required
    - `ts` integer, required — Bucket start (epoch milliseconds).
  - `from` integer, required — Range start (epoch milliseconds).
  - `name` string, required
  - `period_seconds` integer, required
  - `to` integer, required — Range end (epoch milliseconds).

## Other responses

- `400` — Bad request
- `403` — Forbidden

---

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