# GET /v1/credits (/docs/api/reference/credits/get-credits)



<Endpoint method="GET" path="/v1/credits" auth="X-Api-Key" phase="1" />

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 [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://api.layers.com/v1/credits \
      -H "X-Api-Key: $LAYERS_API_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    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.");
    }
    ```
  </Tab>

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

## Response [#response]

<Response status="200" description="OK">
  ```json
  {
    "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
    }
  }
  ```
</Response>

### Field notes [#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](/docs/api/operational/pricing).

## Errors [#errors]

| Status | Code              | When                    |
| ------ | ----------------- | ----------------------- |
| 401    | `UNAUTHENTICATED` | Missing or invalid key. |
| 503    | `KILL_SWITCH`     | Key or org disabled.    |

## See also [#see-also]

* [Whoami](/docs/api/reference/organizations/whoami) — `creditBalance` echoed on the same call
* [Pricing](/docs/api/operational/pricing) — credit-cost table + top-up flow
* [Errors](/docs/api/operational/errors) — `BILLING_EXHAUSTED` (402) semantics