# get\_\_credits\_balance

`GET /credits/balance`

*Get Credit Balance*

Returns the organization's credit balance for the authenticated user. Includes the stored balance (through `dateBalance`), realtime balance (minus pending consumption since that date), and a breakdown of pending consumption by storage and AI. Only available when the platform is configured with `SUBSCRIPTION_SYSTEM=credits`.

#### TypeScript Client Library

```typescript
public getCreditsBalance = async (): Promise<GetCreditsBalanceResponse> => {
  return this.makeRequest<GetCreditsBalanceResponse>('credits/balance', 'GET', null);
};
```

#### Code Samples

{% tabs %}
{% tab title="Shell" %}

```shell
curl -X GET https://backend.flashback.tech/credits/balance \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'
```

{% endtab %}

{% tab title="HTTP" %}

```http
GET https://backend.flashback.tech/credits/balance HTTP/1.1
Host: backend.flashback.tech
Accept: application/json
Authorization: Bearer {access-token}
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
};

fetch('https://backend.flashback.tech/credits/balance', { method: 'GET', headers })
  .then(res => res.json())
  .then(body => console.log(body));
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://backend.flashback.tech/credits/balance', headers=headers)
print(r.json())
```

{% endtab %}
{% endtabs %}

> Example responses

> 200 Response

```json
{
  "success": true,
  "data": {
    "creditBalance": 5000,
    "dateBalance": "2026-01-29T00:00:00.000Z",
    "realtimeBalance": 4850.5,
    "pendingConsumption": 149.5,
    "breakdown": {
      "storage": 80.2,
      "ai": 69.3
    }
  }
}
```

> 400 Response (credits not enabled)

```json
{
  "success": false,
  "error_code": "CREDITS_NOT_ENABLED",
  "message": "Credits system is not enabled"
}
```

> 404 Response

```json
{
  "success": false,
  "error_code": "USER_NOT_FOUND",
  "message": "User not found"
}
```

> 500 Response

```json
{
  "success": false,
  "error_code": "INTERNAL_ERROR",
  "message": "Failed to retrieve credit balance"
}
```

#### Responses

| Status | Meaning               | Description                            | Schema |
| ------ | --------------------- | -------------------------------------- | ------ |
| 200    | OK                    | Credit balance and breakdown           | Inline |
| 400    | Bad Request           | Credits not enabled or no organization | Inline |
| 404    | Not Found             | User not found                         | Inline |
| 500    | Internal Server Error | Server error                           | Inline |

#### Response Schema (200)

| Name                  | Type                       | Required | Description                                               |
| --------------------- | -------------------------- | -------- | --------------------------------------------------------- |
| » success             | boolean                    | false    | Whether the request succeeded                             |
| » data                | object                     | false    | Balance data                                              |
| »» creditBalance      | number                     | false    | Stored balance through dateBalance                        |
| »» dateBalance        | string (date-time) \| null | false    | Last UTC date through which consumption was applied       |
| »» realtimeBalance    | number                     | false    | creditBalance minus pending consumption                   |
| »» pendingConsumption | number                     | false    | Consumption since dateBalance (not yet in stored balance) |
| »» breakdown          | object                     | false    | Pending consumption by category                           |
| »»» storage           | number                     | false    | Pending credits from storage egress                       |
| »»» ai                | number                     | false    | Pending credits from AI token usage                       |
| » error\_code         | string                     | false    | Set on error                                              |
| » message             | string                     | false    | Error or status message                                   |

#### Security

* **BearerAuth**: Bearer token required.
* **Organization**: User must belong to an organization; balance is for that organization.

#### Notes

* Returns 400 with `CREDITS_NOT_ENABLED` when `SUBSCRIPTION_SYSTEM` is not `credits`.
* `realtimeBalance` is the effective balance for enforcement (stored balance minus consumption since `dateBalance`).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flashback.tech/support-reference/platform-api-reference/credits/get__credits_balance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.