Query organization usage metrics with the Neon API

You can use the Neon API to retrieve project level consumption metrics for your organization Metric Description Plan Availability Project level (granular) Project level metrics available at hourly, da...

You can use the Neon API to retrieve project-level consumption metrics for your organization:

Metric	Description	Plan Availability
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:

Bash

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:

JSON

{
  "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"
    }
  ]
}

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.

Bash

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.

JSON

{
  "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:

Bash

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.