> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laburen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits - Balance

> Get the current credit balance of your organization and whether it can run agent messages

<Note>
  Este endpoint requiere autenticacion. Inclui tu API key en el header `Authorization: Bearer <API_KEY>`. Ver [Autenticacion](/api-reference/authentication) para mas detalles.
</Note>

Returns the current credit balance of the authenticated organization and whether it can run agent messages right now. Use this endpoint to:

* Show the remaining credits in your own app
* Warn the user before the balance runs out (you choose the threshold)
* Block an action before running it when the organization can no longer run agent messages

`canRun` and `blockReason` are computed with the same rules the platform applies before running an agent message, so a `canRun: false` here means the next message would be rejected.

This endpoint is meant to be called from a backend. It does not allow cross-origin browser requests: do not expose your API key in a browser.

<Warning>
  `canRun: true` only means the organization has some balance left. A message is allowed while any balance remains, even a fraction of a credit, and in that case only the remaining balance is charged. It does not guarantee there are enough credits for an expensive action: leave a margin in your own threshold. The balance is also a snapshot: other usage can happen between this call and your action.
</Warning>

### Response

<ResponseField name="billingModel" type="string">
  How the organization is billed. Valid values: `credits`, `legacy`.

  * `credits`: the organization has at least one active credit bucket (plan or purchased credits).
  * `legacy`: older billing model limited by number of queries. `credits` is `null` in this case.
</ResponseField>

<ResponseField name="credits" type="object | null">
  Credit amounts summed across all active buckets. `null` when `billingModel` is `legacy`. Amounts are rounded to 6 decimals.

  <Expandable title="Credits object" defaultOpen>
    <ResponseField name="total" type="number">
      Total credits of all active buckets, including the ones already used up.
    </ResponseField>

    <ResponseField name="used" type="number">
      Credits already used: `total - remaining`.
    </ResponseField>

    <ResponseField name="remaining" type="number">
      Credits still available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="canRun" type="boolean">
  `false` when the next agent message would be rejected because of the balance or billing status.
</ResponseField>

<ResponseField name="blockReason" type="string | null">
  Why the organization cannot run agent messages. `null` when `canRun` is `true`. Valid values, in the order they are checked:

  | Value | When |
  | - | - |
  | `payment_overdue` | The subscription payment is past due (`past_due`) |
  | `no_credits` | The organization has credit buckets and no credits left |
  | `query_limit` | Legacy billing: the plan's query limit was reached |
  | `free_plan_limit` | Free plan (or no active subscription): the 5 included agent messages were already used |
</ResponseField>

### Error Responses

| Status Code | Type | Description |
| - | - | - |
| 401 | UNAUTHORIZED | The authenticated session has no organization |
| 403 | Forbidden | Missing or invalid API key (plain text body `Forbidden`) |
| 404 | Not Found | HTTP method other than `GET` |

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request GET 'https://dashboard.laburen.com/api/credits/balance' \
  --header 'Authorization: Bearer <API_KEY>'
  ```

  ```javascript JavaScript theme={null}
  const apiUrl = 'https://dashboard.laburen.com/api';
  const apiKey = '<API_KEY>';

  const response = await fetch(`${apiUrl}/credits/balance`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
    },
  });

  const balance = await response.json();

  if (!balance.canRun) {
    console.log(`Blocked: ${balance.blockReason}`);
  } else if (balance.credits && balance.credits.remaining < 5) {
    console.log('Low balance warning');
  }
  ```

  ```python Python theme={null}
  import requests

  api_url = "https://dashboard.laburen.com/api"
  api_key = "<API_KEY>"

  response = requests.get(
      f"{api_url}/credits/balance",
      headers={
          "Authorization": f"Bearer {api_key}",
      },
  )

  balance = response.json()
  print(balance)
  ```
</RequestExample>

<ResponseExample>
  ```json Credits theme={null}
  {
    "billingModel": "credits",
    "credits": {
      "total": 150,
      "used": 137.5,
      "remaining": 12.5
    },
    "canRun": true,
    "blockReason": null
  }
  ```

  ```json Legacy (blocked) theme={null}
  {
    "billingModel": "legacy",
    "credits": null,
    "canRun": false,
    "blockReason": "query_limit"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.