Skip to content
Theme
Upload a photo Upload
Theme
Theme
Upload a photo

Developers

Credits and ledger endpoints

Read the available balance and the credit history with GET /v1/balance and GET /v1/ledger.

On this page
  1. Get the balance
  2. List the ledger
  3. Entry types
  4. How API jobs will spend credits
  5. Low balance alerts

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#

GET /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.

curl
# 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

// 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";
JavaScript
// 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}`);
200 OK
{
  "object": "balance",
  "available": 1000,
  "livemode": false,
  "as_of": "2026-11-17T09:30:12Z"
}
FieldTypeWhat it is
objectstringAlways "balance".
availableintegerCredits you can spend now.
livemodebooleantrue for live keys.
as_ofstringWhen the balance was read (ISO 8601, UTC).

List the ledger#

GET /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
curl "https://studio-api.mutexai.net/v1/ledger?limit=3" \
  -H "Authorization: Bearer $MUTEXAI_API_KEY"
200 OK
{
  "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
}
FieldTypeWhat it is
idstringThe entry id (le_…).
typestringWhat happened. See the list below.
creditsintegerThe change to the available balance. Negative means credits left it.
balance_afterintegerThe available balance after this change.
descriptionstringA short description for people.
created_atstringWhen it happened (ISO 8601, UTC).

Entry types#

TypeMeaning
purchaseCredits bought in a pack.
grantFree credits: sign-up, monthly, bonus, goodwill, or a sandbox refill.
reserveCredits held for a job that started.
captureHeld credits used for delivered work. They left the available balance when they were held, so a capture does not lower it again.
releaseHeld credits returned because work failed or was not needed.
refundUnused credits removed because the money was refunded.
expireCredits that reached their expiry date.
adjustmentA correction by our team, always with a reason.
reversalCredits 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.

Type at least 2 letters. Use the arrow keys to move and Enter to open.

    Type at least 2 letters. Use the arrow keys to move and Enter to open.