> For the complete documentation index, see [llms.txt](https://docs.nerovasystems.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nerovasystems.com/guides/observe-and-account/usage.md).

# Meter usage for billing

Usage reports the billable jobs a tenant consumed in a billing period, against an allowance you supply. Use it to meter your own billing on top of Nerova's ledger: only verified, billable work counts, and work awaiting evidence is reported separately instead of being billed early.

> **Experimental.** The `/api/v1/**` operations on this page are callable with your Live key (`nrv_live_`), which runs on the free testing allowance until a commercial agreement is signed or a card is saved. See [Lifecycle and availability](https://docs.nerovasystems.com/documentation/api/lifecycle).

## What you'll build

A per-tenant metering job: at each billing cutoff it reads the meter, reconciles pending work, and produces the numbers your billing runs on. Platform accounts report consumption per tenant. The job-count fields below describe a technical usage response, not the definition of SaaS pricing or credit-funded Testing allowance.

## Prerequisites

* An activated tenant and an API key with `usage:read`; see [Authentication](https://docs.nerovasystems.com/documentation/getting-started/authentication).

This meter reports billable jobs. For per-merchant conversation, booking, and token counts to price your own plans, use `GET …/usage/summary` and the usage webhooks in [Track and limit usage by your plans](/guides/observe-and-account/track-and-limit-usage.md).

## 1. Call the meter

All three query parameters are required. `PeriodStart` (inclusive) and `PeriodEnd` (exclusive) define the billing period in UTC, and `IncludedAllowance` is the number of jobs you include for the tenant in that period:

```bash
curl --request GET \
  --url "https://api.nerovasystems.com/api/v1/tenants/{tenantId}/usage?PeriodStart=2026-01-01T00:00:00Z&PeriodEnd=2026-02-01T00:00:00Z&IncludedAllowance=100" \
  --header "Accept: application/json" \
  --header "Authorization: ******"
```

## 2. Read the meter

The response is a complete billing statement for the period:

* `directBillableJobs` is the raw count of billable jobs recorded; `adjustmentCount` and `adjustmentDelta` show corrections applied, and `consumedBillableJobs` is the net result.
* `allowanceConsumed`, `remainingAllowance`, and `overageCount` split the net consumption against the `includedAllowance` you supplied: overage is what you would bill beyond the included amount.
* `pendingReconciliationCount` is work whose outcome is not yet verified. It is not billed yet; do not invoice it.
* `availability` is `Available`, `Degraded`, or `Unavailable`, with `reason` explaining anything other than `Available`. `meterVersion` and `asOf` record which metering rules ran and when, so a statement can be reproduced later.

## 3. Reconcile before invoicing

Pending jobs become billable (or are discarded) once Nerova verifies their outcome against the provider. Re-read the meter after your period ends and delay invoicing until `pendingReconciliationCount` reaches zero or your grace window closes. Once the period is closed, the meter is frozen: attempts to change it are rejected with `409` and code `billing_usage.closed_period_conflict`, so late corrections belong to the next period's adjustments.

## Next steps

* Sell your own plans on top of Nerova's token billing, and count and cap each merchant's AI conversations, bookings, and tokens: [Track and limit usage by your plans](/guides/observe-and-account/track-and-limit-usage.md).
* Inspect the receipts behind every billed job: [Audit work and receipts](/guides/observe-and-account/work-and-receipts.md).
* The same meter, rendered in the console: [Usage](https://docs.nerovasystems.com/documentation/console/usage).
* Full request and response shapes: [Usage reference](https://docs.nerovasystems.com/api-reference/usage).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nerovasystems.com/guides/observe-and-account/usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.