> This page location: Building on Neon > Embedded Postgres > Query consumption metrics > Full Neon documentation index: https://neon.com/docs/llms.txt > > Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md > Summary: The Neon consumption metrics API (/consumption_history/v2) returns project usage metrics for compute, storage, data transfer, extra branches, and Functions, plus per-branch metrics. It is available on Launch, Scale, Agent, and Enterprise plans. Use the project endpoint for project totals and invoicing inputs; use the branch endpoint to attribute compute, storage, and Functions usage to individual branches, CI environments, or development workflows. Granularity options are hourly, daily, and monthly. Calls do not wake suspended compute endpoints. # Querying consumption metrics Learn how to query project consumption metrics for usage-based plans using the Neon API Last updated: 2026-10-31 Using the Neon API, you can query consumption metrics to track your resource usage. This page covers the two v2 metrics endpoints for usage-based plans. To monitor usage in the Console instead, see [Monitor billing and usage](https://neon.com/docs/introduction/monitor-usage). | API | Endpoint | Description | Plan availability | | --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------- | | **Project metrics (usage-based)** | `/consumption_history/v2/projects` | Returns project metrics for compute, storage, data transfer, extra branches, and Functions | Launch, Scale, Agent, Enterprise | | **Branch metrics** | `/consumption_history/v2/branches` | Returns 10 project metrics broken down by branch, across one or more projects | Launch, Scale, Agent, Enterprise | **Tip:** **Which API should I use?** - For usage totals per project, use the [project metrics API](https://neon.com/docs/guides/consumption-metrics#request-overview). It's the only endpoint that returns all 12 project metrics, including snapshot storage, extra branches, and Functions metrics. - To attribute usage to individual branches within a project, for example, to see which CI or development branches are driving compute, storage, or Functions usage, use the [branch metrics API](https://neon.com/docs/guides/consumption-metrics#branch-metrics). - For legacy metrics on older plans, see the [legacy APIs](https://neon.com/docs/guides/consumption-metrics-legacy). **Note: API reference: legacy vs v2** In the [API reference](https://neon.com/docs/reference/api), two similarly named pages cover different paths. **Retrieve project consumption metrics (legacy plans)** is **`GET /consumption_history/projects`** and lists older metrics such as `active_time_seconds` and `compute_time_seconds`. **Retrieve project consumption metrics** (no "legacy plans" in the title) is **`GET /consumption_history/v2/projects`** and documents usage-based metrics, including snapshot storage and Functions metrics, in the **`metrics`** parameter. That v2 page matches this guide; see **[Retrieve project consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project-v2)**. ## Request overview Retrieves consumption metrics for Launch, Scale, Agent, and Enterprise plan projects. Returns project usage metrics. History begins at the time of upgrade. Results are ordered by time in ascending order (oldest to newest). Issuing a call to this API does not wake a project's compute endpoint. **Endpoint:** ```bash GET https://console.neon.tech/api/v2/consumption_history/v2/projects ``` ### Metrics The response includes these usage metrics: | Metric | Raw unit | Converted unit | Description | | ----------------------------------------- | --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `compute_unit_seconds` | CU-seconds | CU-hours | CPU time weighted by compute size | | `root_branch_bytes_month` | byte-months | GB-months | Storage consumed by root branches | | `child_branch_bytes_month` | byte-months | GB-months | Storage consumed by child branches (delta from parent) | | `instant_restore_bytes_month` | byte-months | GB-months | Instant restore (PITR) history storage | | `snapshot_storage_bytes_month` | byte-months | GB-months | Storage for [branch snapshots](https://neon.com/docs/guides/backup-restore): manual snapshots are full; scheduled snapshots are full for the first snapshot, then incremental (delta) for subsequent snapshots in the schedule | | `public_network_transfer_bytes` | bytes | GB | Data transfer over the public internet | | `private_network_transfer_bytes` | bytes | GB | Data transfer over private networks (for example, AWS PrivateLink) | | `extra_branches_month` | branch-hours | branch-months | All child branches per hour (subtract plan allowance before billing) | | `functions_active_capacity_microseconds` | capacity-microseconds | Capacity-Hours | Time Functions spend actively using CPU | | `functions_waiting_capacity_microseconds` | capacity-microseconds | Capacity-Hours | Time Functions spend waiting on I/O | | `functions_invocations` | invocations | million invocations | Number of function calls | | `functions_egress_bytes` | bytes | GB | Data sent by Functions | Use `snapshot_storage_bytes_month` for invoice-aligned, time-windowed snapshot storage reporting. The four Functions metrics are available from both v2 endpoints. For current Functions rates, see [Plans](https://neon.com/docs/introduction/plans#functions). To convert these raw values into readable units and, where applicable, calculate costs, see [Usage and cost calculations](https://neon.com/docs/introduction/usage-calculations). ### Required parameters - **`from`** (date-time, required): Start date-time for the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. The earliest allowed value is March 1, 2024, at 00:00:00 UTC. Metrics are returned from when the account upgraded to an eligible plan, which may be later. The range must respect the granularity limits (hourly: last 168 hours; daily: last 60 days; monthly: last year). - **`to`** (date-time, required): End date-time for the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. The range must respect the same granularity limits as `from`. - **`granularity`** (string, required): 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, required): Organization for which the project consumption metrics should be returned. - **`metrics`** (array of strings, required): List of metrics to include in the response. Possible values: `compute_unit_seconds`, `root_branch_bytes_month`, `child_branch_bytes_month`, `instant_restore_bytes_month`, `snapshot_storage_bytes_month`, `public_network_transfer_bytes`, `private_network_transfer_bytes`, `extra_branches_month`, `functions_active_capacity_microseconds`, `functions_waiting_capacity_microseconds`, `functions_invocations`, `functions_egress_bytes`. Can be an array of parameter values or a comma-separated list in a single parameter value. ### Date format, range, and granularity The API requires timestamps in RFC 3339 format (for example, `2024-06-30T15:30:00Z`), including date, time, and timezone; the `Z` indicates UTC. You can use a [timestamp converter](https://it-tools.tech/date-converter) to generate RFC 3339 formatted timestamps. The earliest allowed `from` value is March 1, 2024, at 00:00:00 UTC. Project metrics begin when the account upgrades to an eligible plan, which may be later. When setting `from` and `to`, keep these limits in mind based on your chosen granularity: | Granularity | Maximum time range | Rounding behavior | | ----------- | ----------------------- | -------------------------------- | | `hourly` | Last 168 hours (7 days) | Rounds to the nearest hour | | `daily` | Last 60 days | Rounds to the start of the day | | `monthly` | Last year | Rounds to the start of the month | Date-time values are automatically rounded according to the specified granularity. For example, `2024-03-15T15:30:00Z` with daily granularity becomes `2024-03-15T00:00:00Z`. ### Optional parameters - **`project_ids`** (array of strings, 0-100 items): Filter to specific project IDs. If omitted, the response contains all projects. Can be an array of parameter values or a comma-separated list in a single parameter value. - **`limit`** (integer, 1-100): Number of projects in the response. Default: `10`. - **`cursor`** (string): Cursor value from the previous response to get the next batch of projects. ## Example request and response Replace `$ORG_ID` and `$NEON_API_KEY` with your organization ID and API key, then run the following to retrieve daily metrics for a date range. ```bash curl --request GET \ --url 'https://console.neon.tech/api/v2/consumption_history/v2/projects?from=2026-02-01T00:00:00Z&to=2026-02-06T00:00:00Z&granularity=daily&org_id=$ORG_ID&metrics=compute_unit_seconds,root_branch_bytes_month,child_branch_bytes_month,instant_restore_bytes_month,snapshot_storage_bytes_month,public_network_transfer_bytes,private_network_transfer_bytes,extra_branches_month,functions_active_capacity_microseconds,functions_waiting_capacity_microseconds,functions_invocations,functions_egress_bytes' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $NEON_API_KEY' | jq ``` **Note:** `snapshot_storage_bytes_month` reflects snapshot storage for billing over the selected time window. Manual snapshots are billed as full snapshots. Scheduled snapshots are billed as full snapshots for the first scheduled snapshot, then as incremental (delta) storage for subsequent scheduled snapshots.
Response body ```json { "projects": [ { "project_id": "delicate-dawn-54854667", "periods": [ { "period_id": "90c7f107-3fe7-4652-b1da-c61f71043128", "period_plan": "launch", "period_start": "2026-02-02T18:04:52Z", "consumption": [ { "timeframe_start": "2026-02-04T00:00:00Z", "timeframe_end": "2026-02-05T00:00:00Z", "metrics": [ { "metric_name": "compute_unit_seconds", "value": 84 }, { "metric_name": "root_branch_bytes_month", "value": 758513664 }, { "metric_name": "instant_restore_bytes_month", "value": 98344 }, { "metric_name": "snapshot_storage_bytes_month", "value": 0 }, { "metric_name": "public_network_transfer_bytes", "value": 1414 } ] }, { "timeframe_start": "2026-02-05T00:00:00Z", "timeframe_end": "2026-02-06T00:00:00Z", "metrics": [ { "metric_name": "compute_unit_seconds", "value": 236 }, { "metric_name": "root_branch_bytes_month", "value": 758611968 }, { "metric_name": "instant_restore_bytes_month", "value": 983488 }, { "metric_name": "snapshot_storage_bytes_month", "value": 0 }, { "metric_name": "public_network_transfer_bytes", "value": 2184 } ] } ] } ] } ], "pagination": { "cursor": "delicate-dawn-54854667" } } ```
**Tip:** You can also query individual metrics by specifying only the ones you need in the `metrics` parameter. Metrics with a value of zero for a given timeframe may be omitted from the response. For full API details including all parameters and response schema, see [Retrieve project consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project-v2). To build a request for a custom time range, use the prompt below with an AI assistant. Copy this prompt to have an AI assistant help you build the curl command for your desired time period. [View prompt](https://neon.com/prompts/consumption-api-prompt.md) The following sections cover paging through many projects, polling behavior, and handling errors. ## Pagination The project consumption metrics endpoint uses cursor-based pagination. The response includes a `pagination` object with a `cursor` value (the project ID of the last project in the list). To get the next page, send another request with that `cursor` in the query string and the same `from`, `to`, `granularity`, `org_id`, and `metrics` as your first request. Example request for the next page (using the `cursor` from the previous response): ```bash curl --request GET \ --url 'https://console.neon.tech/api/v2/consumption_history/v2/projects?cursor=divine-tree-77657175&limit=10&from=2024-06-30T00%3A00%3A00Z&to=2024-07-02T00%3A00%3A00Z&granularity=daily&org_id=$ORG_ID&metrics=compute_unit_seconds,root_branch_bytes_month,child_branch_bytes_month,instant_restore_bytes_month,snapshot_storage_bytes_month,public_network_transfer_bytes,private_network_transfer_bytes,extra_branches_month,functions_active_capacity_microseconds,functions_waiting_capacity_microseconds,functions_invocations,functions_egress_bytes' \ --header 'accept: application/json' \ --header 'authorization: Bearer $NEON_API_KEY' ``` In the URL above, the **`cursor`** parameter is `cursor=divine-tree-77657175`. Replace that value with the `cursor` from your previous response's `pagination` object. ## Consumption polling Neon's consumption data is updated approximately every 15 minutes. A minimum interval of 15 minutes between API calls is recommended. For reporting or invoicing, you can pull usage data at that interval or choose your own; Neon does not dictate how often you poll or how you bill your users. The consumption API endpoints share a single rate limiter of approximately 50 requests per minute per account. Neon uses a **token bucket** approach, which refills at a steady rate and allows short bursts within the bucket size, so the limit behaves like a sliding window rather than a fixed reset every minute. For more details, see [Token bucket](https://en.wikipedia.org/wiki/Token_bucket). Calling the consumption APIs does not wake computes that have been suspended due to inactivity, so polling will not increase your consumption. The [project metrics endpoint](https://neon.com/docs/guides/consumption-metrics#request-overview) on this page returns project usage metrics. The legacy APIs return different metrics that don't map to usage-based line items; see [Query consumption metrics (legacy)](https://neon.com/docs/guides/consumption-metrics-legacy) for those endpoints. ## Error responses Common error responses you may encounter: - **403 Forbidden**: This endpoint is not available for your plan. It is only supported with Launch, Scale, Agent, and Enterprise plan accounts. - **404 Not Found**: Account is not a member of the organization specified by `org_id`. - **406 Not Acceptable**: The specified date-time range is outside the boundaries of the specified granularity. Adjust your `from` and `to` values or select a different `granularity`. - **429 Too Many Requests**: Too many requests. Wait before retrying. ## Build a usage dashboard For a full example that uses this API to build a usage dashboard with Next.js (including charts, project filtering, and reporting), see [Building a Usage Dashboard with Neon's Consumption API](https://neon.com/guides/usage-dashboard-consumption-api). The guide includes a [sample application on GitHub](https://github.com/dhanushreddy291/neon-usage-dashboard) that you can clone and run to visualize your usage-based metrics. ## Branch metrics The branch metrics endpoint returns per-branch consumption data across one or more projects. Use it when you need to see which branches within a project are driving usage, for example, attributing compute costs across CI branches, development environments, or feature branches. **Endpoint:** ```bash GET https://console.neon.tech/api/v2/consumption_history/v2/branches ``` ### Metrics Ten of the 12 project metrics are available on this endpoint: | Metric | Description | | ----------------------------------------- | --------------------------------------- | | `compute_unit_seconds` | CPU time weighted by compute size | | `root_branch_bytes_month` | Storage consumed by root branches | | `child_branch_bytes_month` | Storage consumed by child branches | | `instant_restore_bytes_month` | Instant restore (PITR) history storage | | `public_network_transfer_bytes` | Data transfer over the public internet | | `private_network_transfer_bytes` | Data transfer over private networks | | `functions_active_capacity_microseconds` | Time Functions spend actively using CPU | | `functions_waiting_capacity_microseconds` | Time Functions spend waiting on I/O | | `functions_invocations` | Number of function calls | | `functions_egress_bytes` | Data sent by Functions | `extra_branches_month` and `snapshot_storage_bytes_month` are not available on this endpoint. Use the [project metrics endpoint](https://neon.com/docs/guides/consumption-metrics#request-overview) for those. ### Required parameters - **`project_ids`** (array of strings, 1-100, required): Projects to include. Unlike the project endpoint, `project_ids` is always required here. - **`from`** (date-time, required): Start of the consumption period in RFC 3339 format. - **`to`** (date-time, required): End of the consumption period in RFC 3339 format. - **`granularity`** (string, required): `hourly`, `daily`, or `monthly`. Subject to the same window limits as the project endpoint. - **`org_id`** (string, required): Organization ID. - **`metrics`** (array of strings, required): One or more of the 10 supported metrics above. ### Optional parameters - **`branch_ids`** (array of strings, up to 100): Filter to specific branches. If omitted, all branches in the specified projects are returned. - **`limit`** (integer, 1-1000): Branches per page. Default: 100. - **`cursor`** (string): Pagination cursor from the previous response. ### Example request and response ```bash curl --request GET \ --url 'https://console.neon.tech/api/v2/consumption_history/v2/branches?project_ids=$PROJECT_ID&org_id=$ORG_ID&from=2026-05-01T00:00:00Z&to=2026-05-29T00:00:00Z&granularity=daily&metrics=compute_unit_seconds,root_branch_bytes_month,child_branch_bytes_month' \ --header 'Authorization: Bearer $NEON_API_KEY' \ --header 'Accept: application/json' | jq ```
Response body ```json { "branches": [ { "branch_id": "br-young-sky-a1b2c3d4", "project_id": "calm-night-03860858", "periods": [ { "period_id": "7f3a1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "period_plan": "launch", "period_start": "2026-05-01T00:00:00Z", "consumption": [ { "timeframe_start": "2026-05-01T00:00:00Z", "timeframe_end": "2026-05-02T00:00:00Z", "metrics": [ { "metric_name": "compute_unit_seconds", "value": 1440 }, { "metric_name": "root_branch_bytes_month", "value": 875309056 }, { "metric_name": "child_branch_bytes_month", "value": 0 } ] } ] } ] } ], "pagination": { "cursor": "br-young-sky-a1b2c3d4" } } ```
For full API details, see [Retrieve branch consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-branch-v2). --- ## Related docs (Embedded Postgres) - [Embedded Postgres](https://neon.com/docs/guides/embedded-postgres) - [Configure consumption limits](https://neon.com/docs/guides/consumption-limits) - [Query consumption metrics (legacy)](https://neon.com/docs/guides/consumption-metrics-legacy) --- Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/guides/consumption-metrics"}` to https://feedback.neon.tech/ (no auth required).