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

# Retrieve project consumption metrics

`GET /consumption_history/v2/projects`

Returns consumption metrics for up to `limit` projects per page. If `project_ids` is omitted,
projects in the organization are included across pages (use `cursor`). If `project_ids` is
provided, the response is limited to those projects (up to 100). Available for accounts on
Launch, Scale, Agent, Business, and Enterprise plans.

History starts when the account upgrades to an eligible plan.

The `metrics` query parameter is required. Supported values:
`compute_unit_seconds`, `root_branch_bytes_month`, `child_branch_bytes_month`,
`instant_restore_bytes_month`, `public_network_transfer_bytes`, `private_network_transfer_bytes`,
`extra_branches_month`, `snapshot_storage_bytes_month`.

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

## Query parameters

- `cursor` string
- `limit` integer
- `project_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`

Project consumption metrics for the Neon account.

- object
  - `projects` ConsumptionHistoryPerProjectV2[], required
    - `project_id` string, required — The project 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. Project consumption history requires a Launch, Scale, Agent, Business, 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)