---
title: "Retrieve branch consumption metrics"
method: GET
path: "/consumption_history/v2/branches"
tags: ["Consumption"]
---

# Retrieve branch consumption metrics

`GET /consumption_history/v2/branches`

Returns consumption metrics for each branch across one or more projects listed in
`project_ids` (1 to 100 projects). Available for accounts on paid usage-based Launch, Scale,
Agent, and Enterprise plans.

History starts when the account first ingests branch-level consumption data.

The `metrics` query parameter is required. Only these six values are supported on this
endpoint:
`compute_unit_seconds`, `root_branch_bytes_month`, `child_branch_bytes_month`,
`instant_restore_bytes_month`, `public_network_transfer_bytes`, `private_network_transfer_bytes`.

This endpoint does not support `extra_branches_month` or `snapshot_storage_bytes_month`.
Use `GET /consumption_history/v2/projects` for those.

Consumption metrics within each branch are returned in ascending time order (oldest first).
This request does not wake project computes.

## Query parameters

- `cursor` string
- `limit` integer
- `project_ids` string[], required
- `branch_ids` string[]
- `from` string, date-time, required
- `to` string, date-time, required
- `granularity` 'hourly' | 'daily' | 'monthly', required
- `org_id` string, required
- `metrics` string[], required

## Response `200`

Branch consumption metrics for the Neon account.

- object
  - `branches` ConsumptionHistoryPerBranchV2[], required
    - `project_id` string, required — The project that owns the branch
    - `branch_id` string, required — The branch ID
    - `periods` ConsumptionHistoryPerPeriodV2[], required
      - `period_id` string, uuid, required — The ID assigned to the specified billing period.
      - `period_plan` string, required — The billing plan applicable during the billing period.
      - `period_start` string, date-time, required — The start date-time of the billing period.
      - `period_end` string, date-time — The end date-time of the billing period, available for the past periods only.
      - `consumption` ConsumptionHistoryPerTimeframeV2[], required
        - `timeframe_start` string, date-time — The specified start date-time for the reported consumption.
        - `timeframe_end` string, date-time — The specified end date-time for the reported consumption.
        - `metrics` ConsumptionMetricValue[]
          - `metric_name` string, required
          - `value` integer, required
  - `pagination` Pagination — Cursor based pagination is used. The user must pass the cursor as is to the backend. For more information about cursor based pagination, see https://learn.microsoft.com/en-us/ef/core/querying/pagination#keyset-pagination
    - `cursor` string, required

## Other responses

- `403` — Not available for this account. Branch consumption history requires a paid usage-based Launch, Scale, Agent, or Enterprise plan.
- `404` — Account is not a member of the organization specified by `org_id`.
- `406` — The `from` and `to` range is not valid for the selected `granularity`. Adjust the range or choose a different granularity.
- `429` — Too many requests
- `default` — General Error. The request may or may not be safe to retry, depending on the HTTP method, response status code, and whether a response was received. - If no response is returned from the API, a network error or timeout likely occurred. - In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results. The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**. The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout. Any request that returns a `503 Service Unavailable` response is always safe to retry. Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.

---

[API](https://skmtc.net/neon/apis/neon-api.md) · [All operations](https://skmtc.net/neon/apis/neon-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/neon/neon-api/revisions/cfde79a5c713/schema)