> This page location: Embedded Postgres > Query consumption metrics (legacy) > Full Neon documentation index: https://neon.com/docs/llms.txt > Summary: The legacy Neon consumption API provides the `/consumption_history/projects` endpoint that returns active_time_seconds, compute_time_seconds, written_data_bytes, and synthetic_storage_size_bytes for accounts on Scale plans and above (legacy Scale, Business, Enterprise, and usage-based Scale+), with history available from March 1, 2024. This endpoint is not available on Launch and does not return invoice-aligned metrics on usage-based plans. For metrics that match your invoice or for Launch plan access, use the Query consumption metrics page instead. # Query consumption metrics (legacy) Legacy project consumption API for Scale, Business, and Enterprise plans Using the Neon API, you can query project-level consumption metrics with the legacy endpoint. The Management API only allows this path for **Scale plans and above** (legacy **Scale, Business, and Enterprise**, and usage-based **Scale** and higher). It is **not** available on **Launch**; use [`GET /consumption_history/v2/projects`](https://neon.com/docs/guides/consumption-metrics) instead. On every eligible plan, this endpoint returns **legacy metrics** only (active time, compute time, written data, synthetic storage). On a usage-based plan, those metrics do not match your invoice; for invoice-aligned metrics use the [project metrics endpoint](https://neon.com/docs/guides/consumption-metrics) in Query consumption metrics. | API | Endpoint | Description | Available on | | ------------------- | ------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- | | **Project metrics** | `/consumption_history/projects` | Per-project metrics at chosen granularity | Scale, Business, Enterprise (legacy); usage-based Scale+ (not Launch) | Issuing calls to these APIs does not wake a project's compute endpoints. **Tip:** **Which API should I use?** For metrics that match your **invoice** on a usage-based plan (including **Launch**), use the project metrics API in [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics); it is the only endpoint that returns usage-based billing metrics. For a guide to converting those metrics into billing units and calculating costs, see [Usage and cost calculations](https://neon.com/docs/introduction/usage-calculations). Use the endpoints on this page when you need **legacy metrics** and your organization is on **Scale plans and above** (see table above). These paths always return legacy metrics only, even on usage-based Scale+. ## Request overview The legacy endpoints return consumption data for legacy billing plans. Date format, range limits, and granularity are the same as the usage-based endpoint; for details see [Date format, range, and granularity](https://neon.com/docs/guides/consumption-metrics#date-format-range-and-granularity) in Query consumption metrics. Consumption history is available from March 1, 2024, at 00:00:00 UTC. ### Metrics Both endpoints return metrics that align with legacy billing. Default metrics are returned unless you specify otherwise with the `metrics` parameter: | Metric | Unit | Description | | ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `active_time_seconds` | Seconds | Time compute endpoints have been active | | `compute_time_seconds` | Seconds | CPU seconds used by compute endpoints (see [Legacy metric definitions](https://neon.com/docs/guides/consumption-metrics-legacy#legacy-metric-definitions)) | | `written_data_bytes` | Bytes | Total data written to all of a project's branches | | `synthetic_storage_size_bytes` | Bytes | Storage used (logical data + WAL for all branches) | | `data_storage_bytes_hour` | Bytes-Hour | Storage consumed hourly (optional) | | `logical_size_bytes` | Bytes | Logical size consumed (optional) | | `logical_size_bytes_hour` | Bytes-Hour | Logical size consumed hourly (optional) | ### Project-level endpoint **Endpoint:** ```bash GET https://console.neon.tech/api/v2/consumption_history/projects ``` Retrieves consumption metrics per project at the chosen granularity. The same **Scale plans and above** access rule applies as for the account endpoint (not available on **Launch**—use [v2 project metrics](https://neon.com/docs/guides/consumption-metrics) instead). Results are ordered by time in ascending order (oldest to newest). History begins at the time of upgrade. Issuing a call to this API does not wake a project's compute endpoint. #### Required parameters - **`from`** (date-time, required): Start of the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. Consumption history is available from March 1, 2024, at 00:00:00 UTC. The range must respect the granularity limits (hourly: last 168 hours; daily: last 60 days; monthly: last year). - **`to`** (date-time, required): End of 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` (last 168 hours), `daily` (last 60 days), or `monthly` (last year). #### 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. - **`org_id`** (string): Organization for which to return project consumption metrics. If not provided, returns metrics for the authenticated user's projects. - **`metrics`** (array of strings): Metrics to include. If omitted, `active_time_seconds`, `compute_time_seconds`, `written_data_bytes`, and `synthetic_storage_size_bytes` are returned. Possible values: `active_time_seconds`, `compute_time_seconds`, `written_data_bytes`, `synthetic_storage_size_bytes`, `data_storage_bytes_hour`, `logical_size_bytes`, `logical_size_bytes_hour`. Can be an array or comma-separated list. - **`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. The **`include_v1_metrics`** parameter is deprecated; use **`metrics`** instead. If `metrics` is specified, `include_v1_metrics` is ignored. ### Legacy metric definitions **Default metrics** (returned when `metrics` is omitted): - **active_time_seconds**: Seconds. The amount of time the compute endpoints have been active. - **compute_time_seconds**: Seconds. The number of CPU seconds used by compute endpoints, including compute endpoints that have been deleted. For example: 1 CPU for 1 second = 1; 2 CPUs for 1 second = 2. - **written_data_bytes**: Bytes. The amount of written data for all branches. - **synthetic_storage_size_bytes**: Bytes. The space occupied in storage. Synthetic storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches. **Additional metrics** (include via the `metrics` parameter): - **data_storage_bytes_hour**: Bytes-Hour. The amount of storage consumed hourly. - **logical_size_bytes**: Bytes. The amount of logical size consumed. - **logical_size_bytes_hour**: Bytes-Hour. The amount of logical size consumed hourly. ## Example request and response Replace `$NEON_API_KEY` with your API key and include `org_id` if needed. ### Project-level ```bash curl --request GET \ --url 'https://console.neon.tech/api/v2/consumption_history/projects?from=2024-06-30T00:00:00Z&to=2024-07-02T00:00:00Z&granularity=daily&org_id=org-ocean-art-12345678&limit=10' \ --header 'accept: application/json' \ --header 'authorization: Bearer $NEON_API_KEY' ```
Response body (project) ```json { "projects": [ { "project_id": "random-project-123456", "periods": [ { "period_id": "random-period-abcdef", "period_plan": "scale", "period_start": "2024-06-01T00:00:00Z", "period_end": "2024-07-01T00:00:00Z", "consumption": [ { "timeframe_start": "2024-06-30T00:00:00Z", "timeframe_end": "2024-07-01T00:00:00Z", "active_time_seconds": 147472, "compute_time_seconds": 43222, "written_data_bytes": 112730864, "synthetic_storage_size_bytes": 37000959232 }, { "timeframe_start": "2024-07-01T00:00:00Z", "timeframe_end": "2024-07-02T00:00:00Z", "active_time_seconds": 1792, "compute_time_seconds": 533, "written_data_bytes": 0, "synthetic_storage_size_bytes": 0 } ] } ] } ], "pagination": { "cursor": "random-project-123456" } } ```
**Tip:** You can request specific metrics with the `metrics` parameter (for example, `metrics=active_time_seconds,compute_time_seconds`). For full parameter and response details, see [Retrieve project consumption metrics](https://api-docs.neon.tech/reference/getconsumptionhistoryperproject) in the Neon API Reference. The following sections cover paging (project endpoint), polling behavior, and handling errors. ## Pagination The **project-level** 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`, and `granularity` 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/projects?cursor=divine-tree-77657175&limit=10&from=2024-06-30T00%3A00%3A00Z&to=2024-07-02T00%3A00%3A00Z&granularity=daily&org_id=org-ocean-art-12345678' \ --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 legacy and usage-based 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 endpoints on this page return **legacy metrics** only; when your organization is eligible (Scale+), you can call them on legacy or usage-based plans, but responses will not match your invoice on a usage-based plan. For metrics that match your invoice—or for **Launch** plans—see [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics). ## Error responses Common error responses you may encounter: - **403 Forbidden**: These endpoints are not available for your plan. The API response states that access is included with **Scale plans and above** (legacy **Scale, Business, and Enterprise**, and usage-based **Scale** and higher—not **Launch**). - **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. ## Usage-based pricing and legacy API limitations The legacy endpoints on this page were designed for Neon's legacy billing plans and do not align with [usage-based plans](https://neon.com/docs/introduction/plans). If you're on a usage-based plan (Launch, Scale, Agent, or Enterprise), use [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics) for metrics that map to your invoice. **Legacy API:** Uses `synthetic_storage_size_bytes` (logical data + WAL for all branches in one metric). **Usage-based API:** Returns separate metrics that match your invoice: `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`, and `compute_unit_seconds`. The legacy APIs do not provide these. Use the [project metrics endpoint](https://neon.com/docs/guides/consumption-metrics#request-overview) in Query consumption metrics to retrieve them. --- ## 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](https://neon.com/docs/guides/consumption-metrics)