Developers
Credits and ledger endpoints
Read the available balance and the credit history with GET /v1/balance and GET /v1/ledger.
On this page
Two endpoints let your app see the credits in an account: the balance right now, and the history of every change. The API and the web app share one balance and one price table.
Get the balance#
/v1/balance
balance:read
Returns the credits you can spend now in the key's mode. Credits on hold for running jobs are not included. Test keys see the sandbox wallet (topped up to 1,000 each day), never the live balance.
# Your test key from Developers → API keys. Keep it out of your code and your Git history.
export MUTEXAI_API_KEY="mx_test_..."
curl https://studio-api.mutexai.net/v1/balance \
-H "Authorization: Bearer $MUTEXAI_API_KEY"
<?php
// PHP 8.1+ with the curl extension. Read the key from the environment, never from code.
$apiKey = getenv('MUTEXAI_API_KEY');
$curl = curl_init('https://studio-api.mutexai.net/v1/balance');
curl_setopt_array($curl, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.$apiKey,
'Accept: application/json',
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
$data = json_decode($body, true);
if ($status !== 200) {
// Errors are Problem Details: a stable "code" and a "request_id" to quote to support.
throw new RuntimeException("{$data['code']}: {$data['detail']} (request {$data['request_id']})");
}
echo "Available credits: {$data['available']}\n";
// Node.js 18+ (fetch is built in). Run with: MUTEXAI_API_KEY=mx_test_... node balance.mjs
const response = await fetch('https://studio-api.mutexai.net/v1/balance', {
headers: {
Authorization: `Bearer ${process.env.MUTEXAI_API_KEY}`,
Accept: 'application/json',
},
});
const data = await response.json();
if (!response.ok) {
// Errors are Problem Details: a stable "code" and a "request_id" to quote to support.
throw new Error(`${data.code}: ${data.detail} (request ${data.request_id})`);
}
console.log(`Available credits: ${data.available}`);
{
"object": "balance",
"available": 1000,
"livemode": false,
"as_of": "2026-11-17T09:30:12Z"
}
| Field | Type | What it is |
|---|---|---|
object | string | Always "balance". |
available | integer | Credits you can spend now. |
livemode | boolean | true for live keys. |
as_of | string | When the balance was read (ISO 8601, UTC). |
List the ledger#
/v1/ledger
ledger:read
Every change to the available balance, newest first, with cursor pagination (limit 1 to 100, default 20). The ledger is append-only: lines are never changed or deleted. A mistake is fixed with a new line.
curl "https://studio-api.mutexai.net/v1/ledger?limit=3" \
-H "Authorization: Bearer $MUTEXAI_API_KEY"
{
"object": "list",
"data": [
{
"object": "ledger_entry",
"id": "le_01JD3YF8R0T2V4X6Z8B0D2F4H6",
"type": "release",
"credits": 1,
"balance_after": 994,
"description": "Returned: one image could not be made",
"created_at": "2026-11-17T09:41:05Z"
},
{
"object": "ledger_entry",
"id": "le_01JD3YF2K4M6P8R0T2V4X6Z8B0",
"type": "reserve",
"credits": -7,
"balance_after": 993,
"description": "Held for a product set",
"created_at": "2026-11-17T09:40:11Z"
},
{
"object": "ledger_entry",
"id": "le_01JD3XQ0A2C4E6G8J0L2N4Q6S8",
"type": "grant",
"credits": 1000,
"balance_after": 1000,
"description": "Sandbox refill",
"created_at": "2026-11-17T09:30:12Z"
}
],
"has_more": true,
"next_cursor": "3",
"livemode": false
}
| Field | Type | What it is |
|---|---|---|
id | string | The entry id (le_…). |
type | string | What happened. See the list below. |
credits | integer | The change to the available balance. Negative means credits left it. |
balance_after | integer | The available balance after this change. |
description | string | A short description for people. |
created_at | string | When it happened (ISO 8601, UTC). |
Entry types#
| Type | Meaning |
|---|---|
purchase | Credits bought in a pack. |
grant | Free credits: sign-up, monthly, bonus, goodwill, or a sandbox refill. |
reserve | Credits held for a job that started. |
capture | Held credits used for delivered work. They left the available balance when they were held, so a capture does not lower it again. |
release | Held credits returned because work failed or was not needed. |
refund | Unused credits removed because the money was refunded. |
expire | Credits that reached their expiry date. |
adjustment | A correction by our team, always with a reason. |
reversal | Credits taken back after a payment was reversed. |
How API jobs will spend credits#
Low balance alerts#
To act before you run out, subscribe to credits.low_balance (coming soon) or read /v1/balance on a schedule. Buying credits is done in the app: see Buying credits.
Still stuck? Email [email protected] with what you tried and, for API problems, the request_id.