> ## Documentation Index
> Fetch the complete documentation index at: https://docs.square1.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quota feedback

> The wellspring receipt block and the quota headers

Every chat completion reports your quota standing through two channels.
They exist because of stream timing: headers must flush before generation
starts, while the body block can wait for the final figures.

## 1. The `wellspring` block (exact)

A vendor-extension object on the response body, sibling of `usage`:

```json theme={null}
"wellspring": {
  "request_id": "abc123...",
  "session": {
    "request_pct": 0.42,
    "used_pct": 12.3,
    "remaining_pct": 87.7,
    "resets_at": "2026-08-30T04:00:00.000Z",
    "resets_in_seconds": 17520
  },
  "weekly": { "...": "same shape" },
  "rpm": { "limit": 10, "remaining": 9 }
}
```

* **Exact** post-request accounting, for streams and non-streams alike.
  On streams it arrives as the final data frame before `data: [DONE]`.
* `request_pct` — how much of the pool **this request** consumed. Only
  present when your plan surfaces it.
* Best-effort: if receipt generation fails internally the block is
  omitted; the completion itself is never broken by it.

## 2. Response headers (estimate on streams)

| Header                                           | Meaning                                                                                                |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `x-request-id`                                   | This request's log ID                                                                                  |
| `x-ratelimit-limit-requests`                     | Per-model RPM limit                                                                                    |
| `x-ratelimit-remaining-requests`                 | RPM remaining this minute                                                                              |
| `x-ratelimit-reset-requests`                     | Seconds until the RPM window resets                                                                    |
| `x-session-used-pct` / `x-session-remaining-pct` | Session pool standing                                                                                  |
| `x-session-reset`                                | Seconds until the session resets (integer — the ISO timestamp lives in `wellspring.session.resets_at`) |
| `x-weekly-used-pct` / `x-weekly-remaining-pct`   | Weekly pool standing                                                                                   |
| `x-weekly-reset`                                 | Seconds until the weekly pool resets (integer)                                                         |

On **non-streaming** requests these are exact. On **streaming** requests
they are reservation-time estimates (headers leave before the model has
generated anything) — read the `wellspring` block for the real figures.

<Note>
  Percentages only, everywhere. Raw weighted-token numbers are never
  exposed, so don't try to reverse-engineer pool sizes from these values —
  pace against `remaining_pct` and `resets_at` instead.
</Note>

## Browser caveat

These custom headers are **not exposed to cross-origin browser
JavaScript** (no `Access-Control-Expose-Headers` today). If your client
runs in a browser, use the `wellspring` body block — it's in the response
body and always readable.

## Two request IDs

Don't confuse the two identifying headers:

* `x-request-id` — the request-log ID, tied to quota accounting (chat and
  embeddings responses).
* `x-sq1-request-id` — the correlation ID, present on every response of
  every endpoint. Use this one when reporting issues.