Get credits

Read the credit balance this API key can spend

curl --request GET \
  --url https://api.samsa.ai/public/v1/credits \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.samsa.ai/public/v1/credits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.samsa.ai/public/v1/credits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.samsa.ai/public/v1/credits"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.samsa.ai/public/v1/credits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "available": 123,
  "spendable_plan_credits": 123,
  "plan_credits": 123,
  "topup_credits": 123,
  "period": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  },
  "scope": {
    "team": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    },
    "budget": 2000,
    "used": 500,
    "remaining": 1500
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

GET

credits

Read the credit balance this API key can spend

curl --request GET \
  --url https://api.samsa.ai/public/v1/credits \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.samsa.ai/public/v1/credits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.samsa.ai/public/v1/credits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.samsa.ai/public/v1/credits"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.samsa.ai/public/v1/credits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "available": 123,
  "spendable_plan_credits": 123,
  "plan_credits": 123,
  "topup_credits": 123,
  "period": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  },
  "scope": {
    "team": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    },
    "budget": 2000,
    "used": 500,
    "remaining": 1500
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

Returns what the calling credential — this API key or OAuth connection — can spend right now, alongside the organization-wide totals it is derived from. Requires the usage.read scope. For rates, see Pricing.

Credential-spendable vs organization-wide

The response carries two kinds of number. available and spendable_plan_credits answer “what can this credential spend”; plan_credits and topup_credits are organization-wide balances.

Field	What it is
`available`	Credits this credential can spend right now — `spendable_plan_credits + topup_credits`. This is the number to compare a job’s `estimated_credits` against.
`spendable_plan_credits`	The plan-pool part of `available`: `plan_credits` capped by `scope.remaining`. Equal to `plan_credits` when nothing caps this credential.
`plan_credits`	The organization’s remaining monthly plan pool — not necessarily all spendable by this credential. `0` when the pool is exhausted, or when the subscription is canceled and past its period end (top-ups stay spendable).
`topup_credits`	Remaining credits from valid, non-expired top-up purchases. Top-ups are exempt from team budgets, so they are always fully spendable.
`period`	The organization’s current billing period. Team budget usage resets with it.
`scope`	The budget regime this credential spends under — see below.

Three relations always hold:

available == spendable_plan_credits + topup_credits
spendable_plan_credits <= plan_credits
for an organization with no active teams, spendable_plan_credits == plan_credits

If your organization has no teams, nothing changed for you. scope.type is org, spendable_plan_credits equals plan_credits, and available is still the plan pool plus top-ups.

The budget regime (`scope`)

An organization can reserve parts of its monthly plan pool as per-team budgets, and every API key can be assigned to a team. A credential then 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.

`scope.type`	Meaning	Shortfall error code
`org`	The organization has no active teams (the common case), or it is a budget-exempt system organization. Nothing caps this credential, so `budget`, `used`, and `remaining` are all `null`.	`insufficient_credits`
`team`	The credential is bound to an active team that has its own monthly budget.	`insufficient_team_credits`
`unallocated`	The organization has at least one active team, and this credential is not bound to a budgeted one — it has no team, or its team has no budget of its own. `budget` is the monthly plan allocation minus every active team budget, floored at `0`.	`insufficient_unallocated_credits`

scope.team names the team the credential is bound to, or is null when it is bound to none. scope.remaining is budget - used, floored at 0. A team-bound key whose budget is the binding constraint:

Response

{
  "available": 1450,
  "spendable_plan_credits": 1200,
  "plan_credits": 8031,
  "topup_credits": 250,
  "period": {
    "start": "2026-07-01T00:00:00+00:00",
    "end": "2026-08-01T00:00:00+00:00"
  },
  "scope": {
    "type": "team",
    "team": {
      "id": "7f3c1e28-9b4d-4a61-8e52-0c7d6b5a4f39",
      "name": "Marketing"
    },
    "budget": 10000,
    "used": 8800,
    "remaining": 1200
  }
}

The organization still has 8031 plan credits, but the Marketing budget has 1200 left, so this key can only spend 1200 of them — plus the 250 budget-exempt top-up credits, for 1450 in total.

Predicting and diagnosing a 402

available is the predictor. A job whose estimated_credits is at most available is not refused with an insufficient-credit 402, and conversely such a 402 means the estimate exceeded available — on either number, the credential’s, not the organization’s. One exception: an operational failure inside the deduction itself (for example a degraded balance lookup) is reported as the generic insufficient_credits whatever the regime, without proving anything about available — a plain insufficient_credits where you expected a team-aware code can therefore be transient; retry before treating it as an exhausted balance.

The prediction holds only as long as the credit and budget state does not change between the read and the submit. Another credential of the same organization spending, a top-up lot expiring, a subscription change, a team budget being edited, or a key being reassigned to a different team can all move available — and even change scope.type and therefore which error code you get — without any spend of your own. subscription_inactive is a separate 402, unrelated to this comparison.

When a submit is refused, scope explains it:

scope.type names the budget regime, which is what selects the error code (barring the operational-failure fallback above) — see the table above. It does not tell you which balance ran out: a key under the team regime gets insufficient_team_credits even when the organization’s plan pool, and not the team budget, is what was exhausted.
To find the actual bottleneck under a capped regime (team or unallocated), compare plan_credits with scope.remaining — the smaller one caps spendable_plan_credits. Under org, scope.remaining is null and plan_credits is the only possible bottleneck.
remaining: 0 means that bucket is fully spent for the current period. It is not a precondition of the error: a bucket with remaining: 100 and no top-ups still refuses a job costing 200.

So a key with no team, in an organization whose plan pool is fully allocated to teams, reports available: 0 with scope.type: "unallocated" and remaining: 0 — every submit that costs credits will be refused with insufficient_unallocated_credits until a budget is lowered, the key is assigned to a team with headroom, or top-ups are purchased. See Errors for how to resolve each code.

Authorizations

Authorization

string

header

required

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

Response

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

required

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.

Example:

1450

spendable_plan_credits

integer

required

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.

Example:

1200

plan_credits

integer

required

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

Example:

1200

topup_credits

integer

required

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.

Example:

250

period

BillingPeriod · object

required

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

Show child attributes

scope

PublicCreditsScope · object

required

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.

Show child attributes

Overview

Endpoints

Credential-spendable vs organization-wide

The budget regime (`scope`)

Predicting and diagnosing a 402

Authorizations

Response

​Credential-spendable vs organization-wide

​The budget regime (scope)

​Predicting and diagnosing a 402

Authorizations

Response

Credential-spendable vs organization-wide

The budget regime (`scope`)

Predicting and diagnosing a 402