Obtenir les 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"
  }
}

Renvoie ce que le credential appelant — cette clé API ou cette connexion OAuth — peut dépenser maintenant, ainsi que les totaux de l’organisation dont cela découle. Nécessite le scope usage.read. Pour le détail des tarifs, voir Pricing.

Dépensable par le credential vs. total de l’organisation

La réponse porte deux sortes de nombres. available et spendable_plan_credits répondent à « que peut dépenser ce credential » ; plan_credits et topup_credits sont des soldes à l’échelle de l’organisation.

Champ	Ce que c’est
`available`	Les credits que ce credential peut dépenser maintenant — `spendable_plan_credits + topup_credits`. C’est le nombre auquel comparer les `estimated_credits` d’un job.
`spendable_plan_credits`	La part du pool de plan dans `available` : `plan_credits` plafonné par `scope.remaining`. Égal à `plan_credits` quand rien ne plafonne ce credential.
`plan_credits`	Le pool de plan mensuel restant de l’organisation — pas nécessairement dépensable en entier par ce credential. `0` quand le pool est épuisé, ou quand l’abonnement est résilié et au-delà de la fin de sa période (les top-ups restent dépensables).
`topup_credits`	Les credits restants des achats de top-up valides et non expirés. Les top-ups sont exemptés des budgets d’équipe, donc toujours entièrement dépensables.
`period`	La période de facturation en cours de l’organisation. La consommation des budgets d’équipe se réinitialise avec elle.
`scope`	Le régime de budget sous lequel ce credential dépense — voir ci-dessous.

Trois relations sont toujours vraies :

available == spendable_plan_credits + topup_credits
spendable_plan_credits <= plan_credits
pour une organisation sans équipe active, spendable_plan_credits == plan_credits

Si ton organisation n’a pas d’équipes, rien ne change pour toi. scope.type vaut org, spendable_plan_credits est égal à plan_credits, et available reste le pool de plan plus les top-ups.

Le régime de budget (`scope`)

Une organisation peut réserver des parties de son pool de plan mensuel en budgets par équipe, et chaque clé API peut être affectée à une équipe. Un credential dépense alors depuis exactement un bucket, et seule la marge de ce bucket lui est disponible — c’est pourquoi available peut être inférieur aux plan_credits de l’organisation.

`scope.type`	Signification	Code d’erreur en cas d’insuffisance
`org`	L’organisation n’a aucune équipe active (le cas courant), ou c’est une organisation système exemptée du budgeting par équipe. Rien ne plafonne ce credential, donc `budget`, `used` et `remaining` valent tous `null`.	`insufficient_credits`
`team`	Le credential est affecté à une équipe active qui a son propre budget mensuel.	`insufficient_team_credits`
`unallocated`	L’organisation a au moins une équipe active et ce credential n’est pas affecté à une équipe budgétée — il n’a pas d’équipe, ou son équipe n’a pas de budget propre. `budget` est l’allocation mensuelle du plan moins tous les budgets d’équipe actifs, plancher à `0`.	`insufficient_unallocated_credits`

scope.team nomme l’équipe à laquelle le credential est affecté, ou vaut null quand il n’en a aucune. scope.remaining vaut budget - used, plancher à 0. Une clé liée à une équipe dont le budget est la contrainte active :

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
  }
}

L’organisation a encore 8031 credits de plan, mais il reste 1200 au budget Marketing : cette clé ne peut donc dépenser que 1200 d’entre eux, plus les 250 credits de top-up exemptés de budget, soit 1450 au total.

Prédire et diagnostiquer un 402

available est le prédicteur. Un job dont les estimated_credits sont au plus égaux à available n’est pas refusé par un 402 de credits insuffisants, et inversement un tel 402 signifie que l’estimation a dépassé available — dans les deux cas le nombre du credential, pas celui de l’organisation. Une exception : une défaillance opérationnelle dans la déduction elle-même (par exemple une lecture de solde dégradée) est signalée comme le code générique insufficient_credits quel que soit le régime, sans rien prouver sur available — un simple insufficient_credits là où tu attendais un code lié aux équipes peut donc être transitoire ; réessaie avant de le traiter comme un solde épuisé.

La prédiction ne tient que si l’état des credits et des budgets ne change pas entre la lecture et la soumission. Un autre credential de la même organisation qui dépense, un lot de top-up qui expire, un changement d’abonnement, un budget d’équipe modifié ou une clé réaffectée à une autre équipe peuvent tous déplacer available — et même changer scope.type, et donc le code d’erreur obtenu — sans aucune dépense de ta part. subscription_inactive est un 402 distinct, sans lien avec cette comparaison.

Quand une soumission est refusée, scope l’explique :

scope.type nomme le régime de budget, et c’est lui qui sélectionne le code d’erreur (hormis le repli opérationnel ci-dessus) — voir le tableau ci-dessus. Il ne dit pas quel solde s’est épuisé : une clé sous le régime team reçoit insufficient_team_credits même quand c’est le pool de plan de l’organisation, et non le budget d’équipe, qui était épuisé.
Pour trouver la véritable contrainte sous un régime plafonné (team ou unallocated), compare plan_credits à scope.remaining — le plus petit des deux plafonne spendable_plan_credits. Sous org, scope.remaining vaut null et plan_credits est la seule contrainte possible.
remaining: 0 signifie que ce bucket est entièrement dépensé pour la period en cours. Ce n’est pas une condition préalable de l’erreur : un bucket avec remaining: 100 et sans top-ups refuse toujours un job coûtant 200.

Ainsi une clé sans équipe, dans une organisation dont le pool de plan est entièrement alloué aux équipes, rapporte available: 0 avec scope.type: "unallocated" et remaining: 0 — chaque soumission qui coûte des credits sera refusée avec insufficient_unallocated_credits jusqu’à ce qu’un budget soit abaissé, que la clé soit affectée à une équipe ayant de la marge, ou que des top-ups soient achetés. Voir Erreurs pour la résolution de chaque code.

Autorisations

Authorization

string

header

requis

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

Réponse

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

requis

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.

Exemple:

1450

spendable_plan_credits

integer

requis

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.

Exemple:

1200

plan_credits

integer

requis

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

Exemple:

1200

topup_credits

integer

requis

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.

Exemple:

250

period

BillingPeriod · object

requis

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

Show child attributes

scope

PublicCreditsScope · object

requis

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

Vue d'ensemble

Points de terminaison

Obtenir les credits

Dépensable par le credential vs. total de l’organisation

Le régime de budget (`scope`)

Prédire et diagnostiquer un 402

Autorisations

Réponse

​Dépensable par le credential vs. total de l’organisation

​Le régime de budget (scope)

​Prédire et diagnostiquer un 402

Autorisations

Réponse

Dépensable par le credential vs. total de l’organisation

Le régime de budget (`scope`)

Prédire et diagnostiquer un 402