---
title: "Usage summary"
method: GET
path: "/v1/usage/summary"
tags: ["Account"]
---

# Usage summary

`GET /v1/usage/summary`

## Request

- Base URL: `https://api.kawaa.com`
- URL: `https://api.kawaa.com/v1/usage/summary`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.kawaa.com/oauth/authorize`, token URL `https://api.kawaa.com/oauth/token`, scopes: `analytics:read`)

Credits, API calls, verifications and bulk-job concurrency for the current billing period.

## Response `200`

The summary.

- object
  - `success` unknown, required
  - `data` object, required: The canonical usage shape: the dashboard reads the same one.
    - `credits` object, required
      - `balance` number, required: Spendable now. Fractional: a cached verification costs 0.5.
      - `used_this_month` number, required: What it measures depends on `allowance_basis`: the current billing period for `billing_period`, and a cumulative figure for every other basis (a paid plan with no billing period on file, Free, a sub-account).
      - `monthly_allowance` number, required
      - `allowance_basis` 'billing_period' | 'no_billing_period' | 'one_time_grant' | 'provider_allocation': Only `billing_period` renews. `no_billing_period` (a paid plan with no billing period on file), `one_time_grant` (Free) and `provider_allocation` (a white-label sub-account) are not reset on a schedule, so the figure beside it is cumulative.
      - `rollover_credits` number
      - `bonus_credits` number
      - `expires_at` string, date-time, nullable
    - `api_calls` object, required: Verification REQUESTS, not addresses. One 5,000-address batch is 1 request and 5,000 verifications.
      - `today` integer
      - `this_week` integer
      - `this_month` integer
      - `daily_credits` number
      - `monthly_credits` number
      - `daily_limit` number: Misnamed: carries the CREDIT allowance, not a call ceiling. Nothing meters API calls. Read `daily_credits`.
      - `monthly_limit` number: Misnamed in the same way. Read `monthly_credits`.
    - `verifications` object, required
      - `today` integer
      - `this_week` integer
      - `this_month` integer
      - `total` integer, nullable: Always `null`: a lifetime verification count is not tracked. The only all-time figure is credit spend, and publishing that as a verification count produced fractional 'verifications'.
    - `bulk_jobs` object, required
      - `active` integer
      - `completed_this_month` integer
      - `max_concurrent` integer: Not enforced. A per-plan number (1, 2, 5, 10 or 20) that nothing checks: no route counts running bulk jobs or refuses one over it, so do not throttle against it or present it as a limit. Kept for existing clients; `active` beside it is the measured count.
    - `coverage` object: How much of the billing-period window the job-derived counts (`api_calls`, `verifications`, `bulk_jobs`) actually cover. Job rows expire at the plan's result retention, so on Free `this_month` covers the last 7 days, not the month. The shorter windows (today, this week) fit inside retention on every plan. Optional: when it is absent, treat coverage as not stated.
      - `requested_days` integer, required: Days from the window's start to now, rounded up (what was asked for).
      - `covered_days` integer, required: Days the figures actually cover.
      - `covered_from` string, date-time, required: Start of the covered window.
      - `covered_to` string, date-time, required: End of the covered window. Usually the present; a window whose billing period ended in the past ends then instead.
      - `retention_days` integer, required: How long the account's current plan keeps verification results.
      - `complete` boolean, required: True when the figures cover the whole requested window.
      - `reason` 'plan_retention' | 'null', nullable, required: Why the window was shortened, or null when it was not.
    - `billing_period` object, required: All three are `null` on a plan with no period, and also when a paid plan's period could not be resolved, which is unknown rather than absent. For a short time after a renewal, until its payment is recorded, `credits.used_this_month` has not been reset: it holds the previous period's spend and anything spent since, and this covers the same stretch, from when the counter was last reset up to now, with `days_remaining` 0.
      - `start` string, date-time, nullable
      - `end` string, date-time, nullable
      - `days_remaining` integer, nullable
    - `partial` object: Names the sections whose counts could NOT BE READ. Their numbers are zero-filled placeholders, not measurements. Render them as unavailable, not as zero.
      - `api_calls` unknown
      - `verifications` unknown
      - `bulk_jobs` unknown

## Other responses

- `401`: No credential, or one that is not accepted. `code` distinguishes `API_KEY_SUSPENDED` (subscription ended; restartable) from `API_KEY_REVOKED`, `SESSION_EXPIRED` and `OAUTH_TOKEN_EXPIRED` (a connected app's one-hour access token lapsed: refresh it and retry, or sign in again if no refresh token was issued or the refresh is refused).
- `403`: Refused, and **the code says which of three problems it is**, and they need different remedies: - `INSUFFICIENT_SCOPE`: the credential is valid but not scoped for this route. With an API key, issue one that carries the scope named in the message. With an OAuth access token, connect the app again asking for that scope as well as the ones it has, unless the message says a connected app can never be given it; then use an API key with every scope the message names, or have the account owner do it in the dashboard. - `PLAN_UPGRADE_REQUIRED`: the account's plan does not include the feature. **No key of any scope reaches it**, so issuing another is wasted work; the remedy is a plan change. Returned by the verification routes for `options.enrich`, and by the finder, the monitors, the audit log, auto-clean and the white-label routes. - `PLAN_LIMIT_EXCEEDED`: the plan includes the feature and the account is at its ceiling (webhook endpoints, team seats, integrations, auto-clean lists). Delete one or upgrade. - `FORBIDDEN`: refused for a reason none of the above covers. `ErrorCode` is an open set, so branch on the code with a default rather than exhaustively.
- `429`: Too many requests. When the server knows how long to wait, `Retry-After` says so and `error.retry_after_seconds` carries the same number; the `X-RateLimit-*` headers say where you stand.
- `default`: Any status this operation does not list. Kawaa's own errors carry the error envelope. The gateway in front of the API can answer any operation with its own bare body (`GatewayError`): a `503` after about 29 seconds, when the request may still have run and been charged, a `413` for a body over about 6 MB, or a `400` for a path with malformed percent-encoding.

---

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