Ottieni i credits
Leggi il saldo di credits che questa chiave API può spendere.
usage.read. Per i dettagli sui prezzi, vedi Prezzi.
Spendibile dalla credenziale vs. totale dell’organizzazione
La risposta contiene due tipi di numeri.available e spendable_plan_credits rispondono
a «quanto può spendere questa credenziale»; plan_credits e topup_credits sono saldi
a livello di organizzazione.
available == spendable_plan_credits + topup_creditsspendable_plan_credits <= plan_credits- per un’organizzazione senza team attivi,
spendable_plan_credits == plan_credits
scope.type è org,
spendable_plan_credits è uguale a plan_credits e available è ancora il pool del
piano più i top-up.Il regime di budget (scope)
Un’organizzazione può riservare parti del suo pool mensile del piano come budget per
team, e ogni chiave API può essere assegnata a un team. Una credenziale spende allora da
esattamente un bucket, e le è disponibile solo il margine di quel bucket — ecco perché
available può essere inferiore ai plan_credits dell’organizzazione.
scope.team indica il team a cui la credenziale è assegnata, oppure è null quando non è
assegnata a nessuno. scope.remaining è budget - used, con minimo 0.
Una chiave legata a un team il cui budget è il vincolo attivo:
8031 credits di piano, ma al budget Marketing ne restano
1200: questa chiave può quindi spenderne solo 1200, più i 250 credits di top-up
esenti da budget, per un totale di 1450.
Prevedere e diagnosticare un 402
available è il predittore. Un job i cui estimated_credits sono al massimo pari ad
available non viene rifiutato con un 402 di credits insufficienti e, viceversa, un tale
402 significa che la stima ha superato available — in entrambi i casi il numero
della credenziale, non quello dell’organizzazione. Un’eccezione: un guasto operativo
nella detrazione stessa (per esempio una lettura del saldo degradata) viene segnalato
come il generico insufficient_credits
qualunque sia il regime, senza provare nulla su available — un semplice
insufficient_credits dove ti aspettavi un codice team-aware può quindi essere
transitorio; riprova prima di trattarlo come un saldo esaurito.
Quando un invio viene rifiutato, scope lo spiega:
scope.typeindica il regime di budget, ed è questo a selezionare il codice di errore (salvo il fallback operativo di cui sopra) — vedi la tabella sopra. Non dice quale saldo si è esaurito: una chiave nel regimeteamriceveinsufficient_team_creditsanche quando è il pool del piano dell’organizzazione, e non il budget del team, a essere esaurito.- Per trovare il vincolo reale sotto un regime limitato (
teamounallocated), confrontaplan_creditsconscope.remaining— il minore dei due limitaspendable_plan_credits. Sottoorg,scope.remainingènulleplan_creditsè l’unico vincolo possibile. remaining: 0significa che quel bucket è completamente speso per laperiodcorrente. Non è una precondizione dell’errore: un bucket conremaining: 100e senza top-up rifiuta comunque un job che costa200.
available: 0 con scope.type: "unallocated" e remaining: 0 —
ogni invio che costa credits verrà rifiutato con insufficient_unallocated_credits finché un budget non
viene abbassato, la chiave non viene assegnata a un team con margine, o non vengono
acquistati top-up. Vedi Errori per come
risolvere ciascun codice.Autorizzazioni
Organization API key as a bearer token: Authorization: Bearer samsa_sk_....
Risposta
Successful Response
GET /credits body — what the CALLING credential can spend (ADR §10, SAM-1029).
Two kinds of number:
available/spendable_plan_creditsanswer "what can THIS API key or OAuth connection spend right now" — capped by its team budget bucket (scope), so a job estimated at or belowavailableis not rejected withinsufficient_team_credits/insufficient_unallocated_credits.plan_credits/topup_creditsare the ORGANIZATION-wide balances.
All amounts are balances (not allocations), and
available == spendable_plan_credits + topup_credits always holds, as does
spendable_plan_credits <= plan_credits (they are equal whenever no team
budget applies).
Total credits the calling credential can spend right now — the sum of spendable_plan_credits and topup_credits. Capped by the credential's team budget bucket (see scope), so it can be lower than the organization-wide plan_credits.
1450
Plan-pool credits the calling credential can spend right now: plan_credits capped by scope.remaining. Equal to plan_credits when no team budget applies.
1200
The ORGANIZATION's remaining monthly subscription-pool credits — not necessarily all spendable by this credential (see spendable_plan_credits). 0 when the plan pool is exhausted or the subscription is canceled and past its period end (top-up credits stay spendable).
1200
Remaining credits from valid (non-expired) top-up purchases. Top-ups are exempt from team budgets, so they are always fully spendable by any credential of the organization.
250
The org subscription's current billing-period bounds (ISO-8601).
The credit bucket the calling credential spends from (SAM-1029).
Organizations can reserve parts of their monthly plan pool for teams. A
credential (API key or OAuth connection) spends from exactly ONE bucket, and
only that bucket's headroom is available to it — which is why available
can be lower than the organization-wide plan_credits. The shortfall rule
is cost > available (spendable_plan_credits + topup_credits): a submit
is refused with an insufficient-credit 402 when the deduction,
re-evaluating the same numbers at execution time, finds the estimated cost
above available — insufficient_credits under the uncapped org regime,
insufficient_team_credits under team, and
insufficient_unallocated_credits under unallocated (operational
failures inside the deduction fall back to the generic
insufficient_credits, whatever the regime). This response is a
point-in-time snapshot, not a reservation: concurrent spends, top-up lots
expiring, a canceled subscription's period ending, or a degraded balance
lookup can make the deduction-time numbers differ from the ones reported
here, and other checks can reject a request regardless of credits.
type names the budget regime and selects which of those codes a balance
shortfall raises — it does not say which balance ran out: under a capped
regime the smaller of plan_credits and remaining limits
spendable_plan_credits.
remaining: 0 means this bucket has no plan-pool headroom left for the
current period (spent down, or never allocated any); it is NOT a
precondition of the error — a bucket with remaining: 100 and no top-ups
still refuses a job costing 200.

