Neon exposes usage metrics in the Neon Console and through the Neon API. These metrics can answer questions like:

  • What's my current bill?
  • How much storage am I using?
  • How many compute hours have I used?
  • How many projects do I have?
  • How many branches do I have?

View usage metrics in the Neon Console

Usage metrics in the console can be found on the Billing page, the Project Dashboard, and the Branches page.

Billing page

You can monitor billing and usage for all projects in your Neon account from the Billing page in the Neon Console.

  1. Navigate to the Neon Console.
  2. Select your Profile.
  3. Select Billing from the menu.

Here you will find the current bill and total usage for all projects in your Neon account.

Usage metrics on the Billing page include:

  • Storage: Storage is the total volume of data and history stored in Neon, measured in gigabyte months (GB-month. Data is your logical data size. History is your data’s change history that is used to enable branching-related features, which you can configure for each project via the restore window setting. The displayed storage value reflects your current usage.

  • Compute: The total number of compute hours used during the current billing period. Compute usage is reset to zero at the beginning of each month. The monthly compute hour allowance differs by plan.

  • Archive storage: The total number of gigabyte-months (GB-month used for archived branches. Branches that are older than 14 days and have not been accessed for the past 24 hours are stored in cost-efficient archive storage. The displayed storage value reflects your current usage.

  • Projects: Number of projects currently active in your account. The displayed value reflects your current usage, including any extra projects that have been automatically added as a result of exceeding your plan allowance.

    The Peak usage value is the highest number of projects used during the current billing period. When you exceed your plan's project allowance, extra project units are automatically allocated and billed based on the number of additional units needed to cover your extra usage, prorated from the date the extra was allocated. Project units and their cost are defined according to your Neon plan. Peak usage resets at the beginning of the next billing period.

  • Data transfer The total volume of data transferred out of Neon (egress). Neon does not charge for egress data, but there is an allowance of 5 GB per month for Free Plan users. For all other plans, Neon maintains a reasonable usage policy. For more, see Data transfer. This metric only applies to the Free Plan.

    note: billing metrics for pre-2025 custom contract customers

    If you signed a contract with Neon prior to 01/01/2025, different billing metrics apply:

    • Storage is measured in GiBs instead of [GB-month](/docs/reference/glossary#gb-month, and if you exceed your contract's monthly storage allowance, extra storage units are automatically allocated and billed. Extra storage charges are applied based on the number of additional storage units needed to cover peak storage usage during the current billing period, prorated from the date the extra storage was allocated. Peak usage resets at the beginning of the next billing period.
    • Written data is the total volume of data written from compute to storage over the during the monthly billing period, measured in gigibytes (GiB).

    If you have questions or want to change the billing metrics defined in your contract, please contact your Neon sales representative.

    Monitor billing and usage

Interpreting usage metrics

  • Compute usage is tracked in compute hours. A compute hour is 1 active hour for a compute with 1 vCPU. For a compute with .25 vCPU, it takes 4 active hours to use 1 compute hour. On the other hand, if your compute has 4 vCPUs, it takes only 15 minutes to use 1 compute hour.

    note

    On the Free Plan, you have 191.9 compute hours/month—enough to run a primary 0.25 CU compute 24/7. Up to 5 of those compute hours can be used for non-default branch computes. Autoscaling up to 2 vCPU with 8 GB RAM is available for extra performance during peak times, but please be aware that autoscaling can consume your compute hours more quickly, potentially impacting the ability to run a primary 0.25 CU compute 24/7. If you use Autoscaling or Read Replicas, you'll need to monitor your compute hours to ensure you don't run out before the end of the month.

  • Storage includes your data size and history. Neon maintains a history of changes to support branching-related features such as instant restore. The Launch plan supports up to a 7-day restore window, the Scale plan allows up to 14 days, and the Business plan offers up to 30 days. The default is 1 day on all plans. Keep in mind that the restore window increases storage. More history requires more storage. To manage the amount of history you retain, you can configure the restore window setting for your project. See Configure restore window.

  • Archive storage usage reflects how much data from inactive branches has been archived in cost-efficient storage. To minimize storage costs, Neon automatically archives branches that are older than 14 days and have not been accessed for 24 hours. Both conditions must be true for a branch to be archived. If you actively use all of your branches, you shouldn't expect to see archive storage use. Only expect to see usage if you have branches that more than two weeks old that gone unaccessed for 24 hours or more at some point during the month.

  • What about extra usage?

    The Launch plan supports extra storage, archive storage, and compute usage. The Scale and Business plans support extra storage, archive storage, compute, and project usage. Any extra usage is automatically allocated and billed when you exceed the allowances included in your plan's base fee. The extra usage is reflected in your monthly usage on the Billing page. See Extra usage to learn more.

Project Dashboard

Project usage is displayed across the top of the Project Dashboard.

Project usage banner project dashboard

The Projects page provides an Account Usage banner. This banner shows usage for all of your Neon projects for the current billing period.

Account usage banner project dashboard

Branches page

The Branches page in the Neon Console provides branch-specific metrics, including:

  • Compute hours: The number of computer hours used by the branch's primary compute in the current billing period.
  • Data size: The size of the data on the branch, not including history.
  • Last active: The data and time the branch was last active.

To view the branches in your Neon project:

  1. In the Neon Console, select a project.
  2. Select Branches to view the branches for the project.

You can select a branch from the table to view additional details about the branch.

Retrieve usage metrics with the Neon API

You can retrieve a variety of usage metrics using the Neon API.

Any user can query usage metrics for a branch or a project, as described below. See:

monitoring usage for a large number of projects

Scale and Business plan users can use Neon's advanced consumption endpoints to monitor account and project usage. These endpoints, described in our Partner's Guide, are recommended when monitoring usage for a large number of projects. See:

Get branch details

This example shows how to retrieve branch details using the Get branch details API method. Usage data is highlighted. Refer to the response body section of the Get branch details documentation for descriptions.

curl --request GET \
     --url https://console.neon.tech/api/v2/projects/summer-bush-30064139/branches/br-polished-flower-a5tq1sdv \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' | jq

Response body

{
  "branch": {
    "id": "br-polished-flower-a5tq1sdv",
    "project_id": "summer-bush-30064139",
    "name": "main",
    "current_state": "ready",
    "logical_size": 427474944,
    "creation_source": "console",
    "default": true,
    "protected": false,
    "cpu_used_sec": 2505,
    "compute_time_seconds": 2505,
    "active_time_seconds": 9924,
    "written_data_bytes": 1566733560,
    "data_transfer_bytes": 40820887,
    "created_at": "2024-04-02T12:54:33Z",
    "updated_at": "2024-04-10T17:43:21Z"
  }
}

Get project details

This example shows how to retrieve project details using the Get project details API method. Usage data is highlighted. Refer to the response body section of the Get project details documentation for descriptions.

curl --request GET \
     --url https://console.neon.tech/api/v2/projects/summer-bush-30064139 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' |jq

Response body

{
  "project": {
    "data_storage_bytes_hour": 113808080168,
    "data_transfer_bytes": 40821459,
    "written_data_bytes": 1566830744,
    "compute_time_seconds": 2785,
    "active_time_seconds": 11024,
    "cpu_used_sec": 2785,
    "id": "summer-bush-30064139",
    "platform_id": "aws",
    "region_id": "aws-us-east-2",
    "name": "summer-bush-30064139",
    "provisioner": "k8s-neonvm",
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 0.25,
      "suspend_timeout_seconds": 0
    },
    "settings": {
      "allowed_ips": {
        "ips": [],
        "protected_branches_only": false,
        "protected_branches_only": false
      },
      "enable_logical_replication": false
    },
    "pg_version": 16,
    "proxy_host": "us-east-2.aws.neon.tech",
    "branch_logical_size_limit": 204800,
    "branch_logical_size_limit_bytes": 214748364800,
    "store_passwords": true,
    "creation_source": "console",
    "history_retention_seconds": 86400,
    "created_at": "2024-04-02T12:54:33Z",
    "updated_at": "2024-04-10T17:26:07Z",
    "synthetic_storage_size": 492988552,
    "consumption_period_start": "2024-04-02T12:54:33Z",
    "consumption_period_end": "2024-05-01T00:00:00Z",
    "quota_reset_at": "2024-05-01T00:00:00Z",
    "owner_id": "8d5f604c-d04e-4795-baf7-e87909a5d959",
    "owner": {
      "email": "alex@domain.com",
      "branches_limit": -1,
      "subscription_type": "launch"
    },
    "compute_last_active_at": "2024-04-10T17:26:05Z"
  }
}