Skip to main content
GET
/
credits
Read the organization's remaining credit balance
curl --request GET \
  --url https://api.samsa.ai/public/v1/credits \
  --header 'Authorization: Bearer <token>'
{
  "available": 123,
  "plan_credits": 123,
  "topup_credits": 123,
  "period": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  }
}
Returns { available, plan_credits, topup_credits, period } for the key’s organization — the total spendable balance plus its split into subscription (plan) and top-up credits, and the current billing period. Requires the usage.read scope. For pricing detail, see Pricing.

Authorizations

​
Authorization
string
header
required

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

Headers

​
authorization
string | null

Response

Successful Response

GET /credits body — the org's REMAINING credit balances (ADR §10).

All three amounts are balances (not allocations), so available == plan_credits + topup_credits always holds.

​
available
integer
required

Total credits spendable right now — the sum of plan_credits and topup_credits.

Example:

1450

​
plan_credits
integer
required

Remaining monthly subscription-pool credits. 0 when the plan pool is exhausted or the subscription is canceled and past its period end (top-up credits stay spendable).

Example:

1200

​
topup_credits
integer
required

Remaining credits from valid (non-expired) top-up purchases.

Example:

250

​
period
BillingPeriod · object
required

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