Skip to main content
GET
Read the credit balance this API key can spend
Gibt zurück, was das aufrufende Credential — dieser API-Key oder diese OAuth-Verbindung — gerade ausgeben kann, zusammen mit den organisationsweiten Summen, aus denen sich das ergibt. Erfordert den usage.read Scope. Für Preisdetails siehe Preise.

Credential-verfügbar vs. organisationsweit

Die Antwort enthält zwei Arten von Zahlen. available und spendable_plan_credits beantworten „was kann dieses Credential ausgeben“; plan_credits und topup_credits sind organisationsweite Stände. Drei Beziehungen gelten immer:
  • available == spendable_plan_credits + topup_credits
  • spendable_plan_credits <= plan_credits
  • für eine Organisation ohne aktive Teams gilt spendable_plan_credits == plan_credits
Wenn deine Organisation keine Teams hat, ändert sich für dich nichts. scope.type ist org, spendable_plan_credits entspricht plan_credits, und available ist weiterhin der Plan-Pool plus Top-ups.

Das Budget-Regime (scope)

Eine Organisation kann Teile ihres monatlichen Plan-Pools als Budgets pro Team reservieren, und jeder API-Key kann einem Team zugewiesen werden. Ein Credential gibt dann aus genau einem Bucket aus, und nur der Spielraum dieses Buckets steht ihm zur Verfügung — deshalb kann available niedriger sein als die organisationsweiten plan_credits. scope.team nennt das Team, dem das Credential zugewiesen ist, oder ist null, wenn es keinem zugewiesen ist. scope.remaining ist budget - used, nach unten auf 0 begrenzt. Ein team-gebundener Key, bei dem das Budget die begrenzende Größe ist:
Response
Die Organisation hat noch 8031 Plan-Credits, aber vom Marketing-Budget sind 1200 übrig — dieser Key kann also nur 1200 davon ausgeben, plus die 250 von Budgets ausgenommenen Top-up-Credits, insgesamt 1450.

Ein 402 vorhersagen und diagnostizieren

available ist die Vorhersage. Ein Job, dessen estimated_credits höchstens available betragen, wird nicht mit einem Credit-402 abgelehnt, und umgekehrt bedeutet so ein 402, dass die Schätzung available überschritten hat — bei beidem die Zahl des Credentials, nicht die der Organisation. Eine Ausnahme: ein operativer Fehler in der Abbuchung selbst (etwa eine gestörte Saldo-Abfrage) wird unabhängig vom Regime als generisches insufficient_credits gemeldet, ohne etwas über available zu beweisen — ein schlichtes insufficient_credits, wo du einen team-spezifischen Code erwartet hättest, kann also vorübergehend sein; versuche es erneut, bevor du es als erschöpften Stand behandelst.
Die Vorhersage gilt nur, solange sich der Credit- und Budget-Zustand zwischen dem Lesen und dem Absenden nicht ändert. Ein anderes Credential derselben Organisation, das ausgibt, ein ablaufendes Top-up-Lot, eine Abo-Änderung, ein geändertes Team-Budget oder ein Key, der einem anderen Team zugewiesen wird, können available verschieben — und sogar scope.type und damit den Fehlercode ändern — ohne dass du selbst etwas ausgegeben hast. subscription_inactive ist ein separates 402 und hat mit diesem Vergleich nichts zu tun.
Wenn ein Absenden abgelehnt wird, erklärt scope es:
  • scope.type nennt das Budget-Regime, und das wählt den Fehlercode aus (abgesehen vom operativen Fallback oben) — siehe die Tabelle oben. Es sagt dir nicht, welcher Stand erschöpft war: ein Key im team-Regime erhält insufficient_team_credits auch dann, wenn der Plan-Pool der Organisation und nicht das Team-Budget aufgebraucht war.
  • Um unter einem begrenzten Regime (team oder unallocated) die tatsächliche Ursache zu finden, vergleiche plan_credits mit scope.remaining — der kleinere Wert begrenzt spendable_plan_credits. Unter org ist scope.remaining null und plan_credits ist die einzige mögliche Ursache.
  • remaining: 0 bedeutet, dass dieser Bucket für die aktuelle period vollständig ausgegeben ist. Es ist keine Voraussetzung für den Fehler: ein Bucket mit remaining: 100 und ohne Top-ups lehnt einen Job für 200 weiterhin ab.
Ein Key ohne Team in einer Organisation, deren Plan-Pool vollständig an Teams zugewiesen ist, meldet also available: 0 mit scope.type: "unallocated" und remaining: 0 — jedes Absenden, das Credits kostet, wird mit insufficient_unallocated_credits abgelehnt, bis ein Budget gesenkt wird, der Key einem Team mit Spielraum zugewiesen wird oder Top-ups gekauft werden. Siehe Fehler für den Umgang mit jedem Code.

Autorisierungen

Authorization
string
header
erforderlich

Organization API key as a bearer token: Authorization: Bearer samsa_sk_....

Antwort

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
erforderlich

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.

Beispiel:

1450

spendable_plan_credits
integer
erforderlich

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.

Beispiel:

1200

plan_credits
integer
erforderlich

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

Beispiel:

1200

topup_credits
integer
erforderlich

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.

Beispiel:

250

period
BillingPeriod · object
erforderlich

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

scope
PublicCreditsScope · object
erforderlich

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.