Metering Overview

8 min

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:

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.

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:

{
  "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	Stream usage events in for metering
Realtime Usage Feed	Subscribe to a live push of in flight usage and credit burndown