---
title: "Pages through all identities with per-identity keys, month usage, MAU and balance."
method: GET
path: "/admin/identities"
tags: ["admin"]
---

# Pages through all identities with per-identity keys, month usage, MAU and balance.

`GET /admin/identities`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/admin/identities`
- Auth: HTTP bearer

## Query parameters

- `limit` integer
- `offset` integer
- `sort` string

## Response `200`

One page of identities

- IdentityListResponse: Response for `GET /admin/identities`.
  - `identities` IdentitySummary[], required: The page, in the requested order.
    - `balance_pence` integer, required: Prepaid balance, in pence.
    - `created_at` string, required: RFC 3339 creation timestamp.
    - `download_mib` integer, required: Offline-download bytes served to this identity this month, in MiB (rounded up).
    - `email` string, required: Canonical (lowercased) email.
    - `first_success_at` string, nullable: RFC 3339 timestamp of the identity's activation, the earliest `first_success_at` across its keys, or `null` if no key of the identity has ever had a successful metered call.
    - `id` string, required: Identity id (UUID v4).
    - `keys` integer, required: Keys ever issued to the identity (including revoked).
    - `last_active` string, nullable: UTC day (`YYYY-MM-DD`) of the identity's most recent metered call, or `null` if it has not called since `last_seen_at` tracking began.
    - `mau_overdrawn` boolean, required: Whether the identity is MAU-overdrawn this month (fail-open flag).
    - `mau_this_month` integer, required: Distinct monthly active users recorded this month.
    - `month_used` integer, required: Metered calls recorded this calendar month across all its keys (flushed rows only).
    - `monthly_quota` integer, required: The ENFORCED monthly ceiling `month_used` is spent against. Quotas are identity-pooled (`keys::find_for_auth` sums usage across all of an identity's keys and compares against ONE key's `monthly_quota`), and every live verified key carries the same value by construction (`identity::set_identity_quota` writes one value to all of them; there is no per-key setter for identity keys). So the ceiling is MAX over live verified keys, never SUM, which would overstate it by the key count; an earlier revision made exactly that mistake and reported a paying customer's 250,000 plan as a 1,000,000 ceiling. When the identity holds only provisional keys, the ceiling is the provisional allowance instead (a separate all-time pool, not a monthly one). Read together with `month_used` this gives quota burn, the clearest buy signal the gateway produces: a free account pinned at its ceiling wants to pay, and a paid account using a fraction of what it bought is a renewal risk.
    - `plan` string, required: Coarse plan label (`free` by default).
    - `status` string, required: Account lifecycle status (`active`, `suspended`, `closed`).
  - `limit` integer, required: Page size applied.
  - `offset` integer, required: Offset applied.
  - `total` integer, required: Total identities (across all pages).

## Other responses

- `400`: Invalid limit, offset or sort
- `401`: Missing or wrong admin token

---

[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)