---
title: "Retrieve your usage per piece"
method: GET
path: "/billing/usage"
tags: ["Billing"]
---

# Retrieve your usage per piece

`GET /billing/usage`

## Request

- Base URL: `https://developers.ozav.io/v2`
- URL: `https://developers.ozav.io/v2/billing/usage`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

How each paid piece was used in a month (UTC): calls charged to the prepaid credit and their
amount, calls refunded (a call that did not succeed), calls covered by the monthly free
units, and, for a postpaid organization, calls recorded for the monthly statement.

## Query parameters

- `month` string

## Response `200`

The usage.

- BillingUsage
  - `object` 'billing_usage', required
  - `month` string, required: `YYYY-MM`, UTC.
  - `pieces` object[], required
    - `piece` string, required: The paid piece, e.g. `screening`, `signals`, `business_lookup`.
    - `charged_calls` integer, required
    - `charged` object, required
      - `amount` string, required: Decimal string.
      - `currency` 'USD', required
    - `refunded_calls` integer, required
    - `free_calls` integer, required: Calls covered by the monthly free units.
    - `invoiced_calls` integer, required: Postpaid only: calls recorded for the monthly statement.
  - `total_charged` object, required
    - `amount` string, required: Decimal string.
    - `currency` 'USD', required

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `403`: The organization lacks the entitlement (code ENTITLEMENT_REQUIRED) or the key lacks the scope (code INSUFFICIENT_SCOPE). On money-moving requests (POST /transfers, POST /wallets/{wallet_id}/transfers) a compliance hold on the customer answers with code COMPLIANCE_HOLD: the hold is reviewed and lifted on OZAV's side; retrying does not clear it. When the only hold is a pause until pending onboarding documents are received, a withdrawal answers CUSTOMER_DOCUMENTS_PENDING instead: send what `requirements` on GET /customers/{id} lists; OZAV lifts the pause after reviewing it. On OZAV Services (live without the platform's KYB), any API outside decisions, screenings, lists and self-custody wallets answers with code PRODUCTION_NOT_ACTIVATED.
- `503`: A dependency OZAV needs (storage, a resource lookup) could not be reached, so OZAV fails closed rather than guess. Safe to retry with the same `Idempotency-Key` where the operation accepts one.

---

[API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)