---
title: "The calling key's own metered units, day by day and endpoint by endpoint (quota-free: reading it never spends units)."
method: GET
path: "/v1/usage"
tags: ["self-serve"]
---

# The calling key's own metered units, day by day and endpoint by endpoint (quota-free: reading it never spends units).

`GET /v1/usage`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/v1/usage`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

## Query parameters

- `from` string
- `to` string

## Response `200`

Weighted quota units for the calling key (identity-pooled where the key has an identity)

- UsageResponse: Response for `GET /v1/usage`.
  - `balance_millipence` integer, required: Prepaid credit balance of the owning identity, in internal millipence (1p = 1000 millipence); 0 for keys with no ledger, and for an unverified key on an account somebody has verified, which may not see or spend that account's credit.
  - `days` UsageDayUnits[], required: Per-day breakdown, oldest day first. Days with no recorded units are omitted rather than reported as zero.
    - `day` string, required: The UTC day, `YYYY-MM-DD`.
    - `endpoints` object, required: Weighted quota units for that day, keyed by endpoint label (the collapsed label the meter stores, e.g. `/route`, `/route/v1`, `/tiles`). Never a request count.
  - `from` string, required: First day of the reported window, `YYYY-MM-DD` UTC, inclusive.
  - `identity_pooled` boolean, required: Whether the figures below are pooled across the owning identity's keys. True for self-served keys, whose monthly quota is held by the identity and shared by its keys; false for operator keys, which have no identity and are metered individually. An unverified key reads `true` on every address: its pool is the unverified keys of its address requested from the same network.
  - `key_id` string, required: Key id (UUID) of the calling key.
  - `month_used` integer, required: Units counted against the monthly quota right now, the very number the quota check enforces on, so it always agrees with `used_this_month` on `GET /v1/keys/self`. Identity-pooled where applicable, and it includes units buffered but not yet flushed to `usage_counters`, so it can exceed `total_units` for a window that covers the whole month. Independent of `from`/`to`.
  - `monthly_quota` integer, required: Units allowed per calendar month (identity-bound for self-served keys).
  - `to` string, required: Last day of the reported window, `YYYY-MM-DD` UTC, inclusive.
  - `total_units` integer, required: Total weighted quota units across the whole window.
  - `totals` object, required: Window totals in weighted quota units, keyed by endpoint label.

## Other responses

- `400`: Malformed date, `from` after `to`, or a window longer than 92 days
- `401`: Missing, unknown, revoked or expired key

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)