Skip to main content
GET
Read the credit balance this API key can spend
Restituisce ciò che la credenziale chiamante — questa chiave API o connessione OAuth — può spendere adesso, insieme ai totali dell’organizzazione da cui deriva. Richiede lo scope 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. Tre relazioni valgono sempre:
  • available == spendable_plan_credits + topup_credits
  • spendable_plan_credits <= plan_credits
  • per un’organizzazione senza team attivi, spendable_plan_credits == plan_credits
Se la tua organizzazione non ha team, per te non cambia nulla. 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:
Response
L’organizzazione ha ancora 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.
La previsione vale solo finché lo stato dei credits e dei budget non cambia tra la lettura e l’invio. Un’altra credenziale della stessa organizzazione che spende, un lotto di top-up che scade, una modifica dell’abbonamento, un budget di team modificato o una chiave riassegnata a un altro team possono tutti spostare available — e persino cambiare scope.type, e quindi il codice di errore che ricevi — senza alcuna spesa da parte tua. subscription_inactive è un 402 distinto, non legato a questo confronto.
Quando un invio viene rifiutato, scope lo spiega:
  • scope.type indica 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 regime team riceve insufficient_team_credits anche 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 (team o unallocated), confronta plan_credits con scope.remaining — il minore dei due limita spendable_plan_credits. Sotto org, scope.remaining è null e plan_credits è l’unico vincolo possibile.
  • remaining: 0 significa che quel bucket è completamente speso per la period corrente. Non è una precondizione dell’errore: un bucket con remaining: 100 e senza top-up rifiuta comunque un job che costa 200.
Così una chiave senza team, in un’organizzazione il cui pool del piano è interamente allocato ai team, riporta 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

Authorization
string
header
obbligatorio

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_credits answer "what can THIS API key or OAuth connection spend right now" — capped by its team budget bucket (scope), so a job estimated at or below available is not rejected with insufficient_team_credits / insufficient_unallocated_credits.
  • plan_credits / topup_credits are 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).

available
integer
obbligatorio

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.

Esempio:

1450

spendable_plan_credits
integer
obbligatorio

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.

Esempio:

1200

plan_credits
integer
obbligatorio

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).

Esempio:

1200

topup_credits
integer
obbligatorio

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.

Esempio:

250

period
BillingPeriod · object
obbligatorio

The org subscription's current billing-period bounds (ISO-8601).

scope
PublicCreditsScope · object
obbligatorio

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 availableinsufficient_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.