---
title: "Key status for the calling agent (quota-free: polling it never consumes the free tier)."
method: GET
path: "/v1/keys/self"
tags: ["self-serve"]
---

# Key status for the calling agent (quota-free: polling it never consumes the free tier).

`GET /v1/keys/self`

## Request

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

## Response `200`

State, quota, usage, credits and expiry of the calling key

- SelfResponse: Response for `GET /v1/keys/self`.
  - `allowed_origins` string[], required: Origins this key may be called from. Empty means unrestricted, the key works from anywhere, including from a server with no origin at all.
  - `credits_millipence` integer, required: Prepaid credit balance in internal millipence (1p = 1000 millipence), full precision for fractional, tiered per-call prices.
  - `credits_pence` integer, required: Prepaid credit balance of the owning identity, in pence (floor of the internal millipence balance).
  - `download_allowance_mib` integer, required: Monthly offline-download allowance in MiB (identity-bound). A plan or the SDK licence raises this above the free evaluation default.
  - `download_used_mib` integer, required: Offline download bytes served this calendar month, in MiB (rounded up), identity-wide.
  - `email` string, nullable: Delivery email of the owning identity, the key holder already proved control of the key, and the website's checkout derives the billing identity from this rather than trusting client input. Absent on operator (`admin`) keys, which have no identity, and on email-less (`anonymous`) keys.
  - `expires_at` string, nullable: RFC 3339 expiry, present on provisional keys only.
  - `first_success_at` string, nullable: RFC 3339 timestamp of this key's first successful (2xx) metered API call (the activation event) or `null` if it has never had one. The stamp is written by a buffered task, so it can lag the first success by a moment.
  - `identity_keys` integer, required: Number of active keys sharing this identity (including this one).
  - `key_id` string, required: Key id (UUID).
  - `mau_included` integer, required: Included monthly active users per calendar month (identity-bound). A plan or the admin API raises this above the free default.
  - `mau_overdrawn` boolean, required: Whether a new distinct user beyond the included count could not be covered by the prepaid ledger this month. **Fail-open:** requests keep being served regardless; sustained overdraw is a commercial conversation, not a hard stop.
  - `mau_this_month` integer, required: Distinct monthly active users (`X-MapMap-User` identifiers) recorded this calendar month, identity-wide. Flushed rows only, the buffered writer lags by at most the flush interval.
  - `monthly_quota` integer, required: Requests allowed per calendar month (identity-bound for self-served keys).
  - `pending_email` string, nullable: Email-less keys only: the address a live code was sent to by `POST /v1/keys/self/email`, not yet confirmed (absent when none is outstanding).
  - `remaining` integer, required: Free-tier requests remaining this month.
  - `scope` string, required: `"full"` or `"maps"`. A `maps` key may draw tiles, read styles/fonts/sprites, geocode and read its own status; everything else answers 403 `scope-insufficient`.
  - `state` string, required: Lifecycle state: `admin`, `provisional`, `verified` or `anonymous` (issued without an email).
  - `used_this_month` integer, required: Requests used this month (identity-wide for self-served keys, including not-yet-flushed ones for this key).

## Other responses

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