> This page location: Building on Neon > Embedded Postgres > Query consumption metrics (legacy)
> 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 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 (deprecated, always 0) 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

Last updated: 2026-11-20

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 | Deprecated, returns 0 |
| `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).
- **`org_id`** (string, required with a personal API key): Organization for which to return project consumption metrics. An organization API key that is not project-scoped already identifies its organization, so you can omit `org_id` when you use one. To find your organization IDs, see [Finding organizations for consumption queries](https://neon.com/docs/manage/orgs-api-consumption#finding-organizations-for-consumption-queries).

#### 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.
- **`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. The last one is deprecated and returns 0. 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. Deprecated. The API returns 0. Synthetic storage size combined the logical data size and Write-Ahead Log (WAL) size for all branches. Use the [v2 endpoints](https://neon.com/docs/guides/consumption-metrics) for storage.

**Additional metrics** (include via the `metrics` parameter):

- **data_storage_bytes_hour**: Bytes-Hour. Retired. The API returns 0.
- **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 the `org_id` value with your organization ID. With `granularity=daily`, the `from` and `to` values must fall within the last 60 days.

### Project-level

```bash
curl --request GET \
  --url "https://console.neon.tech/api/v2/consumption_history/projects?from=2026-10-01T00:00:00Z&to=2026-10-06T00:00:00Z&granularity=daily&org_id=org-ocean-art-12345678&limit=10" \
  --header 'accept: application/json' \
  --header "authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body (project)</summary>

```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": 0
            },
            {
              "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"
  }
}
```

</details>

**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://neon.com/docs/reference/api/consumption/get-consumption-history-per-project) 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. Pass that value as-is; don't build it from project IDs. 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=2026-10-01T00%3A00%3A00Z&to=2026-10-06T00%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:

- **400 Bad Request**: The request is invalid. For example, `from` is before March 1, 2024. A request made with a personal API key and no `org_id` can also return this error.
- **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**). A request made with a personal API key and no `org_id` can also return this error even when your organization is on an eligible plan; add `org_id`.
- **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:** Reports storage through `synthetic_storage_size_bytes`, which is deprecated and returns 0. Use the v2 storage metrics instead.

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

---

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-legacy"}` to https://feedback.neon.tech/ (no auth required).
