# Read your balance

> The credits you can spend now and when they run out, per credit type, read live — the whole account, not one key.

`GET https://api.refabric.com/v1/account/balance`

**Authentication.** A key with `account:read`: the balance is your account's.

**Common use cases**

- Check your balance before you start a batch.

**See also**

- `GET /v1/account/usage`
- `POST /v1/tasks/{name}/estimate`

Authentication: `Authorization: Key $REFABRIC_API_KEY`, scope `account:read`.

## Header parameters

- `Refabric-Version` (string, _optional_, format: date) — The contract version you wrote against (a date). Absent: the current version.
- `X-Request-ID` (string, _optional_, max length 128) — Your own id for this request; we answer it back under X-Client-Request-ID.

## Response 200

Done: the answer is in the body.

- `balances` (array<object>, _required_) — One entry per credit type.
  Example: `[{"credit_type":"refabric_credits","expiring":[{"at":"2026-10-31T23:59:59Z","credits":400}],"remaining":1200},{"credit_type":"model_credits","expiring":[],"remaining":0}]`
  - `credit_type` (string, _required_) — Which kind of credit an amount is counted in.
    Values: `refabric_credits` (Spent by tasks.); `model_credits` (Credits for model training.)
    Example: `refabric_credits`
  - `remaining` (integer, _required_) — What you can spend now: a job asking for more than this is refused.
    Example: `1200`
  - `expiring` (array<object>, _required_) — When your credits run out, one entry per batch, in the order they are spent. The entries need not add up to `remaining`.
    Example: `[{"at":"2026-10-31T23:59:59Z","credits":400}]`
    - `credits` (integer, _required_) — The credits left in this batch.
      Example: `400`
    - `at` (string | null, _required_) — When they run out (UTC). A plan's credits are used within their billing period; a pack's run to its own date.
      Example: `2026-10-31T23:59:59Z`
- `as_of` (string, _required_) — The moment these figures were read (UTC, ISO-8601).
  Example: `2026-10-05T12:00:00Z`

```json
{
  "balances": [
    {
      "credit_type": "refabric_credits",
      "expiring": [
        {
          "at": "2026-10-31T23:59:59Z",
          "credits": 400
        }
      ],
      "remaining": 1200
    },
    {
      "credit_type": "model_credits",
      "expiring": [],
      "remaining": 0
    }
  ],
  "as_of": "2026-10-05T12:00:00Z"
}
```

## Response 401

No valid API key was sent.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 403

Your key or your plan does not allow this.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 429

Too many requests: wait for the number of seconds in the Retry-After header.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 500

Something went wrong on our side; retry, and quote the request id if it keeps happening.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Request

```python
import os
import requests

url = "https://api.refabric.com/v1/account/balance"

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.refabric.com/v1/account/balance';
const options = {method: 'GET', headers: {Authorization: `Key ${process.env.REFABRIC_API_KEY}`}};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}
```

```bash
curl --request GET \
    --url https://api.refabric.com/v1/account/balance \
    --header "Authorization: Key $REFABRIC_API_KEY"
```