GET /v1/credits

Returns the calling org's current credit balance, billing period usage, and a per-format estimate partners can use for pre-flight checks before firing a generate call. Light read - safe to call on every boot + periodically during a session.

The canonical shape is shared with /v1/whoami, which echoes creditBalance as a single field so you don't need two RTTs on boot.

Example request

curl https://api.layers.com/v1/credits \
  -H "Authorization: Bearer $LAYERS_API_KEY"

const res = await fetch("https://api.layers.com/v1/credits", {
  headers: { "Authorization": `Bearer ${process.env.LAYERS_API_KEY}` },
});
const wallet = await res.json();
if (wallet.balance < wallet.estimatedCreditsPerFormat["slideshow_builder"]) {
  throw new Error("Low credit balance; top up before generating.");
}

import os, requests
res = requests.get(
    "https://api.layers.com/v1/credits",
    headers={"Authorization": f"Bearer {os.environ[\'LAYERS_API_KEY\']}"},
)
wallet = res.json()

Response

{
  "organizationId": "org_2481fa5c-a404-44ed-a561-565392499abc",
  "balance": 6000,
  "available": 5880,
  "includedRemaining": 600,
  "prepaidBalance": 5400,
  "reservedCredits": 120,
  "includedThisPeriod": 1000,
  "usedThisPeriod": 400,
  "currentPeriod": {
    "start": "2026-04-01T00:00:00.000Z",
    "end": "2026-05-01T00:00:00.000Z",
    "usedCredits": 400
  },
  "subscriptionTier": "pro",
  "billingStatus": "active",
  "estimatedCreditsPerFormat": {
    "slideshow_builder": 50,
    "slideshow_remix": 50,
    "video_remix": 120,
    "ugc_remix": 120,
    "auto": 120
  },
  "ingestCostsBilled": {
    "github": false,
    "website": false,
    "appstore": false
  }
}

Field notes

• balance = includedRemaining + prepaidBalance (gross). available = balance - reservedCredits, floored at 0 - what you can actually spend on new work right now. Gate a generate call against available, not balance: generations reserve credits the moment a workflow starts, so available can dip below balance while work is in flight.
• reservedCredits is credit committed to in-flight generations. It exists so balance - reservedCredits === available reconciles client-side. When nothing is running, it's 0 and available === balance.
• includedRemaining is the portion of your subscription's monthly included credits still available in the current period. Rolls over at currentPeriod.end.
• prepaidBalance is topped-up credits that don't expire.
• estimatedCreditsPerFormat is a defensive upper bound - real cost at render time is model-dependent (smaller if the generation lands on a cheaper model, larger for higher-quality video). Use these numbers for UI "you'll spend ~N credits" prompts; the authoritative deduction happens server-side after generation.
• ingestCostsBilled flags whether an ingest call debits partner credits. Today all three are false. If that changes, the flag flips to true before billing begins.

Errors

See also

• Whoami - creditBalance echoed on the same call
• Errors - BILLING_EXHAUSTED (402) semantics