---
operationId: "getConsumptionHistoryPerBranchV2"
method: "GET"
path: "/consumption_history/v2/branches"
tag: "consumption"
stability: "beta"
interfaces: ["api", "sdk"]
---
> API Reference / 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.


### Parameters

- `cursor` (string, query, optional)
  Cursor from the previous response (`pagination.cursor`). Pass it to fetch the next page
  of branches. Pages are ordered by project ID, then branch ID.
  
- `limit` (integer, query, optional)
  Maximum number of branches per page. Allowed range: 1 to 1000. Default: 100.
  
  Default: `100`
- `project_ids` (array, query, required)
  Project IDs to include (required, 1 to 100). Returns metrics for branches in these projects.
  
  Pass multiple IDs as repeated query parameters or a comma-separated list:
  - `project_ids=cold-poetry-09157238&project_ids=quiet-snow-71788278`
  - `project_ids=cold-poetry-09157238,quiet-snow-71788278`
  
- `branch_ids` (array, query, optional)
  Optional branch IDs to filter the response (up to 100). If omitted, all branches in the
  listed projects are included.
  
  Pass multiple IDs as repeated query parameters or a comma-separated list:
  - `branch_ids=br-aged-salad-637688&branch_ids=br-sweet-breeze-497520`
  - `branch_ids=br-aged-salad-637688,br-sweet-breeze-497520`
  
- `from` (string, query, required)
  Specify the start `date-time` for the consumption period.
  The `date-time` value is rounded according to the specified `granularity`.
  For example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`.
  The specified `date-time` value must respect the specified `granularity`:
  - For `hourly`, consumption metrics are limited to the last 168 hours.
  - For `daily`, consumption metrics are limited to the last 60 days.
  - For `monthly`, consumption metrics are limited to the last year.
  
  Branch-level metrics are returned from when the account first ingests branch-level
  consumption data. Periods before that time contain no branch metrics.
  
- `to` (string, query, required)
  Specify the end `date-time` for the consumption period.
  The `date-time` value is rounded according to the specified `granularity`.
  For example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`.
  The specified `date-time` value must respect the specified `granularity`:
  - For `hourly`, consumption metrics are limited to the last 168 hours.
  - For `daily`, consumption metrics are limited to the last 60 days.
  - For `monthly`, consumption metrics are limited to the last year.
  
- `granularity` (string, query, required)
  Specify the granularity of consumption metrics.
  Hourly, daily, and monthly metrics are available for the last 168 hours, 60 days,
  and 1 year, respectively.
  
- `org_id` (string, query, required)
  Organization ID. Metrics are returned for projects in this organization.
  
- `metrics` (array, query, required)
  Required. List the metrics to return. Only these values are supported:
  - `compute_unit_seconds`
  - `root_branch_bytes_month`
  - `child_branch_bytes_month`
  - `instant_restore_bytes_month`
  - `public_network_transfer_bytes`
  - `private_network_transfer_bytes`
  
  Not supported on this endpoint: `extra_branches_month`, `snapshot_storage_bytes_month`.
  Use `GET /consumption_history/v2/projects` for those.
  
  Pass multiple values as repeated query parameters or a comma-separated list:
  - `metrics=compute_unit_seconds&metrics=public_network_transfer_bytes`
  - `metrics=compute_unit_seconds,public_network_transfer_bytes`
  

### Response (200)

- `branches` (array, optional)
  - `project_id` (string, required)
    The project that owns the branch
  - `branch_id` (string, required)
    The branch ID
  - `periods` (array, required)
    - `period_id` (string, required, format: uuid)
      The ID assigned to the specified billing period.
    - `period_plan` (string, required)
      The billing plan applicable during the billing period.
    - `period_start` (string, required, format: date-time)
      The start date-time of the billing period.
      
    - `period_end` (string, optional, format: date-time)
      The end date-time of the billing period, available for the past periods only.
      
    - `consumption` (array, required)
      - `timeframe_start` (string, optional, format: date-time)
        The specified start date-time for the reported consumption.
        
      - `timeframe_end` (string, optional, format: date-time)
        The specified end date-time for the reported consumption.
        
      - `metrics` (array, optional)
        - `metric_name` (string, required)
        - `value` (integer, required)
- `pagination` (object, optional)
  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)

### Code examples

```bash
curl "https://console.neon.tech/api/v2/consumption_history/v2/branches?project_ids=$PROJECT_IDS&from=$FROM&to=$TO&granularity=$GRANULARITY&org_id=$ORG_ID&metrics=$METRICS" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```typescript
import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.getConsumptionHistoryPerBranchV2({
  client: neon.client,
  query: {
    project_ids: process.env.PROJECT_IDS,
    from: process.env.FROM,
    to: process.env.TO,
    granularity: process.env.GRANULARITY,
    org_id: process.env.ORG_ID,
    metrics: process.env.METRICS
  }
});
```

### Errors

**403**
Not available for this account. Branch consumption history requires a paid usage-based
Launch, Scale, Agent, or Enterprise plan.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Default: ``
- `message` (string, required)
  Error message

**404**
Account is not a member of the organization specified by `org_id`.
- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Default: ``
- `message` (string, required)
  Error message

**406**
The `from` and `to` range is not valid for the selected `granularity`. Adjust the range or
choose a different granularity.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Default: ``
- `message` (string, required)
  Error message

**429**
Too many requests
- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Default: ``
- `message` (string, required)
  Error message

**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.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Default: ``
- `message` (string, required)
  Error message