--- title: "Quotas and Stats" description: "Read your account's registration and look-up grants, learn what spends them, and handle the 429 refusal." published: 2026-09-21T23:44:02.390615+00:00 updated: 2026-09-21T23:44:02.390615+00:00 tags: ["parallax", "quotas", "usage"] url: https://xiobjects.com/docs/xio/parallax/quotas-and-stats source: XI Objects --- # Quotas and Stats Each beta account is granted a fixed number of registrations and a fixed number of look-ups. They are lifetime totals, not a rate. There is no self-service top-up: ask the operator. ## Read your usage ```bash curl -sS "$BASE/account/stats" -H "Authorization: Bearer $TOKEN" ``` ```json { "registrations": { "grant": 10, "consumed": 3, "held": 2, "remaining": 7 }, "lookups": { "grant": 50, "consumed": 12, "held": 0, "remaining": 38 }, "callCount": 84 } ``` | Field | Type | Description | |-------|------|-------------| | `registrations.grant` | `int` | Registrations granted to your account. | | `registrations.consumed` | `int` | Registrations actually spent. | | `registrations.held` | `int` | Images reserved right now across your open registration slots. Not yet spent. | | `registrations.remaining` | `int` | `grant` minus `consumed`. It is not reduced by `held`. | | `lookups.grant` | `int` | Look-ups granted to your account. | | `lookups.consumed` | `int` | Look-ups actually spent. | | `lookups.held` | `int` | Query images reserved right now across your open look-up slots. | | `lookups.remaining` | `int` | `grant` minus `consumed`. It is not reduced by `held`. | | `callCount` | `int` | Every authenticated call your account has ever made. | `GET /account/stats` reports your own account only. No other account's stats are a request this API can express. ## What spends a registration One registration, per image that actually registers. That is it. | Event | Registrations | |-------|---------------| | An image registers at commit, or through `POST /registrations` | 1 | | An image refused as already registered or as a derivative | 0 | | An entry that failed at commit | 0 | | An image refused at upload for any reason | 0 | | A commit that was refused or never finished | 0 for what did not register | The charge runs before the engine call, then anything that did not end up registered is settled back. `consumed` reflects what you got, not what was attempted. A commit that is cancelled or fails part way settles exactly like one that completes. ## What spends a look-up | Event | Look-ups | |-------|----------| | A look-up query that produced a verdict, single or batch | 1 | | A registration pre-check that **matched** | 1 | | A registration pre-check that did not match | 0 | | A query the engine refused, or that never reached a verdict | 0 | The pre-check charge is the one that surprises people. When you try to register an image and it is refused as already registered, you were given a global look-up verdict for it, so it costs one look-up. It never costs a registration. ## Reservations An image held in an open slot reserves grant without spending it. That is the `held` figure. Reservations come back when they are released: remove the entry, abandon the slot, let the slot expire, or have the commit refused. Nothing needs to be reclaimed by hand. `remaining` never subtracts `held`. To know what you can still add to a slot, compare `held` against `remaining` yourself. Across all your open registration slots, uncommitted entries may never exceed your remaining registration grant. An image past that bound is refused at upload with `The account's remaining registration grant does not cover this image.` ## An account with no look-ups left cannot register Registration runs a pre-check, and a matched pre-check spends a look-up. The service reserves that look-up before it calls the engine, so an exhausted grant can never be spent to read a verdict for free. With no look-up grant left: - `POST /registrations` answers `429 Quota exceeded` before the engine is asked anything. - A slot upload refuses the image with `The account's remaining lookup grant does not cover this image.`, naming the look-up grant even though the route is the registration one. A look-up slot holding your whole look-up grant blocks registration the same way, until that slot commits or expires. ## The 429 ```json { "title": "Quota exceeded", "status": 429, "detail": "The account's remaining quota does not cover this request.", "registrationRemaining": 1, "lookupRemaining": 0, "traceId": "00-..." } ``` | Extension | Description | |-----------|-------------| | `registrationRemaining` | Registrations left at the moment of refusal. | | `lookupRemaining` | Look-ups left at the moment of refusal. | Both counts are always carried, whichever grant refused the request. Read the one that is `0`. Routes that answer it: `POST /registrations`, `POST /slots/{slotId}/uploads` when no image in the request fits, `POST /slots/{slotId}/commit`, `POST /lookup`, `POST /lookup/slots/{lookupSlotId}/queries` when no image fits, and `POST /lookup/slots/{lookupSlotId}/commit`. A slot upload whose images straddle the edge does not answer `429`. It answers `200 OK`, holds what fits, and refuses each over-edge image on its own with the same two counts on the outcome. ## What to do about it Retrying does not help. A grant is a lifetime total, so a `429` means you are out, not that you are going too fast. Take down registrations you no longer need to free the images, though that does not return spent grant. To raise a grant, ask the operator.