Skip to main content

Telemetry & Metering

Because each tenant is a project, per-customer usage is directly attributable, forming the foundation for billing, plan enforcement, margin analysis, and the validation metering model. Capture two kinds of signals.

Consumption Metrics​

Neon exposes usage through two consumption history endpoints: one per project, one per branch. Both return the same kind of usage time series; they differ only in the level of attribution.

Use the projects endpoint as your metering source of record. In this framework one tenant maps to one project, so per-project usage is per-tenant usage. Reach for the branches endpoint only when a single tenant runs multiple branches and you need to see which one is driving cost.

Projects Endpoint (Recommended)​

GET /consumption_history/v2/projects returns one usage series per project, aggregated across all of its branches. You can get metrics across all projects in one call. It reports all eight usage metrics: compute_unit_seconds; storage as root_branch_bytes_month, child_branch_bytes_month, instant_restore_bytes_month (PITR), and snapshot_storage_bytes_month; public_network_transfer_bytes and private_network_transfer_bytes; and extra_branches_month.

These totals are aligned with Neon invoicing, which makes them the correct basis for billing, plan enforcement, and margin analysis. The frequency of collection is determined by the partner's operational model. Note that Neon refreshes consumption only every ~15 minutes. Reading consumption does not wake suspended computes, and therefore collection never inflates a tenant's bill.

Branches Endpoint (Optional Drill-Down)​

GET /consumption_history/v2/branches breaks the same usage down to individual branches within a project. This is useful when one tenant runs several branches, for example separating a production branch from CI or development branches.

Documentation: Consumption metrics

Fleet Inventory Metrics​

Alongside consumption, track the shape of the fleet using the Neon platform (management) API.

The count that matters is the number of projects, the primary proxy for tenant/customer acquisition and central to the validation requirements. Get it from a single call: GET /projects, passing your org_id to list every project in the organization.

The remaining inventory is hierarchical, so pull it only if you need branch, database, or snapshot counts:

  • GET /projects/{project_id}/branches — branches in a project
  • GET /projects/{project_id}/branches/{branch_id}/databases — databases in a branch
  • GET /projects/{project_id}/snapshots — snapshots in a project

These are per-project (and per-branch) calls, so collecting them across the fleet costs one request per project or branch. Prefer the org-wide GET /projects call as your acquisition metric and treat the rest as optional drill-downs.

Documentation: Neon API reference

What's Next​

  • Use Cases — How telemetry and the rest of the architecture differ for agents vs. platform databases
  • Validation — How these metrics map to the Built-On Neon metering requirements