---
title: "Get the credit balance"
description: "Retrieve the workspace's credit balance and every credit grant with its remaining amount and expiry date."
canonical: "https://lookio.app/docs/api/credits/get-credits"
updated: "2026-10-17"
---

# Get the credit balance

Requires `account:read`.

Reading credits costs nothing. Credits are spent only when [an assistant answers a question](/docs/api/assistants/query-assistant).

The estimated date of the next refill is an estimate, derived from the expiry of the latest monthly grant. It is not a guarantee. See [Credits and plans](/docs/platform/credits-and-plans).

```http
GET https://api.lookio.app/v1/credits
```

## Authorizations

- `Authorization` (bearer, in header, required)

## Response

**200**: Retrieve the credit balance and every grant

- `data` (`object`, required)
- `data.balance` (`integer`, required)
- `data.plan` (`string`, required)
- `data.monthly_allowance` (`integer | null`, required)
- `data.next_refill_estimated_at` (`string,null`, required)
- `data.grants` (`object[]`, required)
- `data.grants.id` (`string`, required)
- `data.grants.type` (`string`, required)
- `data.grants.amount` (`integer`, required)
- `data.grants.used` (`integer`, required)
- `data.grants.remaining` (`integer`, required)
- `data.grants.granted_at` (`string,null`, required)
- `data.grants.expires_at` (`string,null`, required)
- `request_id` (`string`, required)

```json
{
  "data": {
    "balance": 123,
    "plan": "<string>",
    "monthly_allowance": 123,
    "next_refill_estimated_at": null,
    "grants": [
      {
        "id": "<string>",
        "type": "<string>",
        "amount": 123,
        "used": 123,
        "remaining": 123,
        "granted_at": null,
        "expires_at": null
      }
    ]
  },
  "request_id": "<string>"
}
```

**401**: Possible codes: authentication_required, invalid_api_key, api_key_expired, api_key_revoked, invalid_access_key

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**403**: Possible codes: insufficient_scope, feature_not_available, admin_required, permission_denied

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**429**: Possible codes: rate_limited

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**500**: Possible codes: internal_error

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**Example request**

```bash
curl --request GET \
  --url 'https://api.lookio.app/v1/credits' \
  --header 'Authorization: <api-key>'
```