---
title: "Retrieve branch metrics"
method: POST
path: "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics"
tags: ["Branches", "Metrics"]
---

# Retrieve branch metrics

`POST /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics`

## Request

- Base URL: `https://api.xata.tech`
- URL: `https://api.xata.tech/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics`
- Auth: OAuth 2
  - Implicit: `https://auth.xata.io/realms/xata/protocol/openid-connect/auth`
  - Scopes: `metrics:read`

Returns time-series data for one or more metrics of a branch.

## Path parameters

- `organizationID` string, required
- `projectID` string, required
- `branchID` string, required

## Request body

- BranchMetricsRequest
  - `start` string, date-time, required: Start time
  - `end` string, date-time, required: End time
  - `metrics` BranchMetricName[], required: List of metric names to query.
  - `instances` string[]: List of instance IDs to query
  - `aggregations` string[], required: List of aggregations to get, this is how the data-points within the interval are aggregated. Each one will generate a separate time-series per metric in the response.

## Response `200`

Metrics for a branch

- BranchMetrics: A collection of metrics (cpu, memory, disk,...) for each of the instances of a branch
  - `start` string, date-time, required
  - `end` string, date-time, required
  - `results` BranchMetricResult[], required: One entry per requested metric, in the order the metrics were requested.
    - `metric` string, required: Name of the queried metric.
    - `unit` string, required: Unit of the metric (percentage, bytes, ms, etc.)
    - `series` MetricSeries[], required
      - `instanceID` string, required: ID of the instance
      - `aggregation` 'avg' | 'max' | 'min', required: The aggregation used to generate this time-series
      - `values` object[], required
        - `timestamp` string, date-time, required
        - `value` number, required

## Other responses

- `400`: Generic error response for most error conditions
- `401`: Error response when authentication or authorization fails
- `404`: Generic error response for most error conditions
- `5XX`: Unexpected Error
- `default`: Unexpected Error

## Changes

- **2026-11-04** `4bc5ad58a6c6`: 1 breaking
  - the `aggregations` request property's minItems was increased to `1`
- **2026-05-27** `8d02eb2c8759`: 4 breaking, 1 warning
  - the request property `metrics` became required
  - removed the required property `metric` from the response with the `200` status
  - removed the required property `series` from the response with the `200` status
  - removed the required property `unit` from the response with the `200` status
  - …1 more
- **2026-05-26** `f5b0c7bc81f8`: 17 breaking, 8 info
  - added `#/components/schemas/BranchMetricName` to the `metric` request property `allOf` list
  - removed the enum value `connections_active` of the request property `metric`
  - removed the enum value `connections_idle` of the request property `metric`
  - removed the enum value `cpu` of the request property `metric`
  - …21 more
- **2026-04-15** `a2cc5189d200`: 3 breaking, 1 warning, 3 info
  - added the new required request property `metric`
  - the request property `instances` became required
  - removed the required property `results` from the response with the `200` status
  - removed the request property `metrics`
  - …3 more

[Operation history](https://skmtc.dev/xataio/apis/xata-api/changes/organizations/:organizationID/projects/:projectID/branches/:branchID/metrics/post.md)

---

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