Query organization usage metrics with the Neon API

You can use the Neon API to retrieve two types of consumption history metrics for your organization:

Metric	Description	Plan Availability
Account-level	Total usage across all projects in your organization	Scale
Project-level (granular)	Project-level metrics available at hourly, daily, or monthly level of granularity	Scale

Finding organizations for consumption queries

Before querying consumption metrics, you'll need the org_id values for organizations you want to query. Use your personal API key to list all organizations you have access to:

curl --request GET \
     --url 'https://console.neon.tech/api/v2/users/me/organizations' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $PERSONAL_API_KEY' | jq

The response includes details about each organization, including the org_id you'll need for consumption queries:

{
  "organizations": [
    {
      "id": "org-morning-bread-81040908",
      "name": "Morning Bread Organization",
      "handle": "morning-bread-organization-org-morning-bread-81040908",
      "plan": "free_v2",
      "created_at": "2025-04-30T14:43:00Z",
      "managed_by": "console",
      "updated_at": "2025-04-30T14:46:22Z"
    },
    {
      "id": "org-super-grass-41324851",
      "name": "Super Org Inc",
      "handle": "super-org-inc-org-super-grass-41324851",
      "plan": "scale_v2",
      "created_at": "2025-06-02T16:56:18Z",
      "managed_by": "console",
      "updated_at": "2025-06-02T16:56:18Z"
    }
  ]
}

Account-level metrics

To get global totals for all projects in the organization org-ocean-art-12345678, include the org_id in the GET /consumption/projects request. Required parameters:

A start date
An end date
A level of granularity

The following example requests hourly metrics between June 30th and July 2nd, 2024:

curl --request GET \
     --url 'https://console.neon.tech/api/v2/consumption_history/account?from=2024-06-30T15%3A30%3A00Z&to=2024-07-02T15%3A30%3A00Z&granularity=hourly&org_id=org-ocean-art-12345678' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY'

The response will provide aggregated hourly consumption metrics, including active_time_seconds, compute_time_seconds, written_data_bytes, and synthetic_storage_size_bytes, for each hour between June 30 and July 2.

Response body

For attribute definitions, find the Retrieve account consumption metrics endpoint in the Neon API Reference. Definitions are provided in the Responses section.

{
  "periods": [
    {
      "period_id": "random-period-abcdef",
      "period_plan": "scale",
      "period_start": "2024-06-01T00:00:00Z",
      "consumption": [
        {
          "timeframe_start": "2024-06-30T15:00:00Z",
          "timeframe_end": "2024-06-30T16:00:00Z",
          "active_time_seconds": 147452,
          "compute_time_seconds": 43215,
          "written_data_bytes": 111777920,
          "synthetic_storage_size_bytes": 41371988928
        },
        {
          "timeframe_start": "2024-06-30T16:00:00Z",
          "timeframe_end": "2024-06-30T17:00:00Z",
          "active_time_seconds": 147468,
          "compute_time_seconds": 43223,
          "written_data_bytes": 110483584,
          "synthetic_storage_size_bytes": 41467955616
        }
        // ... More consumption data
      ]
    },
    {
      "period_id": "random-period-ghijkl",
      "consumption": [
        {
          "timeframe_start": "2024-07-01T00:00:00Z",
          "timeframe_end": "2024-07-01T01:00:00Z",
          "active_time_seconds": 145672,
          "compute_time_seconds": 42691,
          "written_data_bytes": 115110912,
          "synthetic_storage_size_bytes": 42194712672
        },
        {
          "timeframe_start": "2024-07-01T01:00:00Z",
          "timeframe_end": "2024-07-01T02:00:00Z",
          "active_time_seconds": 147464,
          "compute_time_seconds": 43193,
          "written_data_bytes": 110078200,
          "synthetic_storage_size_bytes": 42291858520
        }
        // ... More consumption data
      ]
    }
    // ... More periods
  ]
}

Project-level metrics (granular)

You can also get similar daily, hourly, or monthly metrics across a selected time period, but broken out for each individual project that belongs to your organization.

Using the endpoint GET /consumption_history/projects, let's use the same start date, end date, and level of granularity as our account-level request: hourly metrics between June 30th and July 2nd, 2024.

curl --request GET \
     --url 'https://console.neon.tech/api/v2/consumption_history/projects?limit=10&from=2024-06-30T00%3A00%3A00Z&to=2024-07-02T00%3A00%3A00Z&granularity=hourly&org_id=org-ocean-art-12345678' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY'

Response body

For attribute definitions, find the Retrieve project consumption metrics endpoint in the Neon API Reference. Definitions are provided in the Responses section.

{
  "projects": [
    {
      "project_id": "random-project-123456",
      "periods": [
        {
          "period_id": "random-period-abcdef",
          "period_plan": "scale",
          "period_start": "2024-06-30T00:00:00Z",
          "consumption": [
            {
              "timeframe_start": "2024-06-30T00:00:00Z",
              "timeframe_end": "2024-06-30T01: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-01T01:00:00Z",
              "active_time_seconds": 1792,
              "compute_time_seconds": 533,
              "written_data_bytes": 0,
              "synthetic_storage_size_bytes": 0
            }
            // ... More consumption data
          ]
        },
        {
          "period_id": "random-period-ghijkl",
          "period_plan": "scale",
          "period_start": "2024-07-01T09:00:00Z",
          "consumption": [
            {
              "timeframe_start": "2024-07-01T09:00:00Z",
              "timeframe_end": "2024-07-01T10:00:00Z",
              "active_time_seconds": 150924,
              "compute_time_seconds": 44108,
              "written_data_bytes": 114912552,
              "synthetic_storage_size_bytes": 36593552376
            }
            // ... More consumption data
          ]
        }
        // ... More periods
      ]
    }
    // ... More projects
  ]
}

Project-level metrics (for the current billing period)

To get basic billing period-based consumption metrics for each project in the organization org-ocean-art-12345678, include org_id in the GET /projects request for consumption metrics:

curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects?org_id=org-ocean-art-12345678' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY'

See more details about using this endpoint on the Manage billing with consumption limits page in our Platform integration guide.

Metric definitions

active_time_seconds — The number of seconds the project’s computes have been active during the period.
compute_time_seconds — The number of CPU seconds used by the project's computes, including computes that have been deleted; for example:
- A compute that uses 1 CPU for 1 second is equal to compute_time=1.
- A compute that uses 2 CPUs simultaneously for 1 second is equal to compute_time=2.
written_data_bytes — The total amount of data written to all of a project's branches.
synthetic_storage_size_bytes — The total space occupied in storage. Synthetic storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches.