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 "X-Api-Key: $LAYERS_API_KEY"

const res = await fetch("https://api.layers.com/v1/credits", {
  headers: { "X-Api-Key": process.env.LAYERS_API_KEY! },
});
const wallet = await res.json();
if (wallet.balance < wallet.estimatedCreditsPerFormat.video_remix) {
  throw new Error("Low credit balance; top up before generating.");
}

import os, requests
res = requests.get(
    "https://api.layers.com/v1/credits",
    headers={"X-Api-Key": os.environ["LAYERS_API_KEY"]},
)
wallet = res.json()

Response

{
  "organizationId": "2481fa5c-a404-44ed-a561-565392499abc",
  "balance": 6000,
  "includedRemaining": 600,
  "prepaidBalance": 5400,
  "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": {
    "video_remix": 120,
    "slideshow_remix": 50,
    "ugc_remix": 120,
    "auto": 120
  },
  "ingestCostsBilled": {
    "github": false,
    "website": false,
    "appstore": false
  }
}

Field notes

• balance = includedRemaining + prepaidBalance. The single number to gate a generate call against.
• 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 (Layers absorbs the upstream cost-of-goods). If that changes, the flag flips to true and we document the exact deduction in pricing.

Errors

See also

• Whoami — creditBalance echoed on the same call
• Pricing — credit-cost table + top-up flow
• Errors — BILLING_EXHAUSTED (402) semantics