Session cap API

Reference

Lookup material for the endpoints behind Apply to existing sessions on the Budgets Limits tab. They change the recorded cap of existing sessions and nothing else: spend, counters, extensions, status and expiry are never changed.

Endpoints

Endpoint	Purpose
POST /api/v1/ui/settings/sessions/cap/preview	Counts the sessions an apply would change and the enforcement impact. Writes nothing.
POST /api/v1/ui/settings/sessions/cap/apply	Changes the matching sessions in one transaction and reports how many changed.
GET /api/v1/ui/settings/sessions/cap/values	Lists the distinct caps existing sessions have, most used first, with their session counts.

Authorization

All three endpoints accept only admin tokens. Viewer, builder and developer tokens receive 403, and a request with missing or invalid credentials receives 401.

Request

Preview and apply take the same body, except that expectedChanged is accepted by apply only. Unknown fields, including unknown scope fields and expectedChanged on preview, are rejected with 400.

Field	Meaning
oldCapUSD	The cap the sessions to change currently have. 0 means unlimited.
newCapUSD	The cap they should have. 0 means unlimited. Must differ from oldCapUSD.
scope.active	Include sessions that can still make requests: every status except expired and revoked.
scope.ended	Include ended sessions: expired and revoked. For these only the recorded cap changes; nothing is enforced on them. Sessions with status inactive (idle) are not ended; scope.active covers them.
scope.includeCustom	Also include sessions with a custom or extended cap.
expectedChanged	Apply only, optional. The total the preview reported.

Both oldCapUSD and newCapUSD are required. Both caps must be finite numbers from 0 to 1000000000, and at least one of scope.active and scope.ended must be true. Otherwise the response is 400.

Which sessions match

Preview and apply use one selection. Sessions whose boundary was inferred (transcript or idle origin) never match, because they carry no cap by design. A session matches when its status is in the selected scope and:

• includeCustom is false: its cap equals oldCapUSD.
• includeCustom is true: its cap differs from newCapUSD.

Preview response

Field	Meaning
activeChange, endedChange	Sessions that would change, split by scope.
skippedCustom	Sessions in the selected statuses kept because their cap is not oldCapUSD. Always 0 when includeCustom is true.
newlyBlocked	Sessions with status active that are not blocked now and whose spend is at or above the new cap.
unblocked	Sessions with status active that are blocked now and would no longer be.
topBlocked, topUnblocked	Up to three sessions with the highest spend behind newlyBlocked and unblocked, each with id, developerId, spentUSD and capUSD.

A session is blocked when its cap is above 0 and its spend is at or above the cap. Degraded, paused, expired and revoked sessions are never counted as blocked or unblocked.

Apply response

Field	Meaning
activeChanged, endedChanged	Sessions changed, split by scope.
changed	The total.
mismatch	true when expectedChanged was sent and differs from changed, because sessions changed after the preview. The apply has already happened; the response reports the difference instead of hiding it.

The change is a single update committed together with its audit entry. If it fails, no session changed and the response is 500. Applying again changes nothing that already has the new cap, and concurrent applies from several sessions or replicas change each session once.

Values response

caps is a list of capUSD and sessions, most used first. Every distinct cap is listed. Inferred sessions are not counted.

Audit entry

An apply that changes at least one session records a configuration audit entry with action sessions.cap_applied, in the same transaction as the change. It carries the actor, the cap before and after (capUSD), the scope (scopeActive, scopeEnded, includeCustom), and activeChanged and endedChanged. An apply that changes nothing records no entry.