---
title: "Get Balances"
method: GET
path: "/v1/entitlements"
tags: ["entitlements"]
---

# Get Balances

`GET /v1/entitlements`

## Request

- Base URL: `https://api.usekeel.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.usekeel.io/v1/entitlements`
- Auth: none declared

Return per-unit balance summary for the org.

## Headers

- `Authorization` string, nullable
- `X-Org-Id` string, nullable

## Response `200`

Successful Response

- EntitlementBalanceResponse: Per-unit balances for an org. Carries ``plan`` so the reset instants below can be stamped HERE rather than at the call site — the same reasoning as ``MeResponse``: a call site that forgets to stamp is indistinguishable from a unit that genuinely does not refill, and telling those apart is the whole point of Q-1597.
  - `balances` EntitlementBalance[], required
    - `unit` string, required
    - `type` string, required
    - `granted` integer, required
    - `spent` integer, required
    - `reserved` integer, required
    - `available` integer, required
    - `enabled` boolean, nullable
    - `cap_current` integer, nullable
    - `period` string, nullable
    - `resets_at` string, nullable
    - `first_week` FirstWeekBlock: An active first-week welcome grant on one unit (connect-onboarding §1.8). The wire shape of :meth:`platform_auth.quota.FirstWeek.to_dict`: ``granted`` is the grant's own delta, ``remaining`` what is left of it (``WELCOME_POOL_SQL``), ``ends_at`` its expiry (ISO-8601, ``Z``). The key is ABSENT -- not null -- whenever no welcome grant is active; the serializers below drop a ``None``.
      - `granted` integer, required
      - `remaining` integer, required
      - `ends_at` string, required
    - `unlimited` boolean, required: Whether this grant is unbounded — SERVED, so no client needs the sentinel (Q-1614). ``granted`` carries ``platform_auth.config.UNLIMITED`` (INT_MAX) for an unlimited plan, a storage artifact whose only job is to not be rendered. keel-app had re-typed that literal in three places with nothing comparing the copies, and a single miss shows a user a nine-digit quota. A computed field cannot be passed in and cannot drift: it is recomputed from ``granted`` on every response, by the same test ``platform_auth.quota.QuotaView`` applies.
  - `plan` string, nullable

## Other responses

- `422`: Validation Error

---

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