---
title: Metering Overview
slug: metering-overview
docTags: 
createdAt: 2026-10-20T00:08:11.630Z
---

:::hint{type="info"}
**Private Beta.** The Metering API is available to selected customers while we harden it for general release. It is served on its own plane and gated by license. To get access for your tenant, talk to your Nue account team.
:::

The Metering API lets your systems stream usage events into Nue and subscribe to a realtime feed of in flight usage and credit burndown. Meters, which define how each product is counted and priced, are set up in Nue, not through this API.

Usage events flow in through ingest, aggregate into metering windows, get priced by the rating pipeline, and draw against credit pools where applicable. You send events in over HTTP, and read usage, balances, and burndown as they move on the realtime feed.

## Base URL

Metering has its own host, separate from the main Nue API:

```text
https://metering.nue.io            production
https://metering.sandbox.nue.io    sandbox
```

Use the host for the environment you are working in.

## Authentication and tenancy

- HTTP requests authenticate with a Nue API key or an authenticated session, exactly as for every other Nue API.
- The gateway resolves your tenant from the credential server side. No parameter, header, or body field can select a tenant, and a caller supplied tenant header is discarded.
- The realtime feed authenticates with a short lived token minted by the gateway. See [Realtime Usage Feed](docId\:B5C8JPbJDYlSxqJYgL5gs).

## Getting access

Metering is in Private Beta. The **Metering license** is granted by Nue per tenant, not self serve. To get Metering for your tenant, reach out to your Nue account team or your sales rep. There is no public sign up while the beta is running.

## Licensing and permissions

Every Metering endpoint is gated on two things: the **Metering license** at the tenant level, and a **role permission** on the API key or session making the call. An administrator grants the permission the call needs to the role behind your key.

| Permission            | Covers                                   |
| --------------------- | ---------------------------------------- |
| View Metering Usage   | See metered usage on the realtime feed   |
| View Metering Credits | See credit burndown on the realtime feed |

The realtime feed requires metering read access; its page notes the specifics. A tenant without the license, or a key whose role lacks the permission, receives `403` or `404`, never partial data. A `403` on a metering route carries `INSUFFICIENT_PERMISSIONS` and names the resource and the permission it needs.

## Data conventions

- **Timestamps** are RFC3339 in UTC on the HTTP interfaces. The realtime feed carries epoch milliseconds.
- **Money and quantities are decimal strings** such as `"12.50"`, never JSON numbers. Parsing them into a float loses precision on figures that reach an invoice, so carry them in a decimal type.
- **Metered event values are whole numbers** (int64) end to end. Fractional event values are rejected at ingest.
- **Identifiers.** Subscriptions are addressed by `subscriptionNumber` such as `SUB-000042`, and customers by `customerId`.

## Versioning

The path version `/v1/` identifies this contract. Additive changes such as new optional fields or new endpoints do not bump the version. Breaking changes ship under a new path version with a deprecation window on the old one. While in Private Beta, fields can still be added.

## Error model

Every HTTP endpoint returns one envelope shape on failure:

```json
{
  "errors": [
    { "code": "INVALID_PARAMETER", "message": "…", "field": "timestamp" }
  ]
}
```

| Status        | Meaning                                                                    |
| ------------- | -------------------------------------------------------------------------- |
| `400`         | Malformed parameter or filter. `code` and `field` identify it.             |
| `401` / `403` | Missing or invalid credential, or missing license or role.                 |
| `404`         | The route exists but the resource does not, or the tenant is not licensed. |
| `429`         | Gateway rate limit exceeded. Retry with backoff.                           |
| `500`         | Server fault. The response carries no internal detail.                     |

## Endpoints

| Endpoint                                            | Purpose                                                         |
| --------------------------------------------------- | --------------------------------------------------------------- |
| [Send Usage Events](docId\:IOTpTtszg97jJ2zdiMOnj)   | Stream usage events in for metering                             |
| [Realtime Usage Feed](docId\:B5C8JPbJDYlSxqJYgL5gs) | Subscribe to a live push of in flight usage and credit burndown |