# Credits and limits

What your account holds and what it may still convert today.

### Retrieve the credit balance

`GET /v1/credits`

Derived from the ledger on every call: there is no balance column, since a cached total drifts under partial failure and the customer is the one who finds out. `unlockCost` is what unlocking one image costs, published so a client never hardcodes it; `tier` says which caps apply.

```bash
curl https://api.vecsnap.com/v1/credits \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
```

Answer 200:

```json
{
  "balance": 184,
  "tier": "free",
  "unlockCost": 1
}
```

Every refusal it may answer: `invalid_api_key` (401), `unauthenticated` (401), `account_required` (403), `account_stopped` (403), `email_unverified` (403), `plan_required` (403), `account_exists` (409), `email_refused` (422), `rate_limited` (429), `internal_error` (500), `auth_unavailable` (503).

### List the credit history

`GET /v1/credits/history`

Every entry that moved the caller's balance, newest first, a page at a time: what added credits (the sign-up grant, packs, a plan's months) and what spent them (unlocks, conversions paid in credits), each with what it meant. Pass a page's `nextCursor` back as `cursor`. Their sum is the balance (`GET /credits`).

| Field | In | Type | Required | What |
| --- | --- | --- | --- | --- |
| `limit` | query | integer, 1 to 100 | no |  |
| `cursor` | query | string | no | A page's `nextCursor`. |

```bash
curl https://api.vecsnap.com/v1/credits/history \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
```

Answer 200:

```json
{
  "object": "list",
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "at": "2026-10-24T12:00:00.000Z",
      "kind": "welcome",
      "amount": 0,
      "pocket": "plan",
      "subject": {
        "name": "Brand colors",
        "imageId": "00000000-0000-4000-8000-000000000000"
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

Every refusal it may answer: `invalid_cursor` (400), `invalid_request` (400), `invalid_api_key` (401), `unauthenticated` (401), `account_required` (403), `account_stopped` (403), `email_unverified` (403), `plan_required` (403), `account_exists` (409), `email_refused` (422), `rate_limited` (429), `internal_error` (500), `auth_unavailable` (503).

### Retrieve today's limits

`GET /v1/limits`

The caps that apply to the caller (a guest, a free account or a customer) and how much of today is used: the same count the create refuses by. `usedToday` counts free conversions (waiting ones included) and refunded holds; a stopped one never ran and is not counted.

```bash
curl https://api.vecsnap.com/v1/limits \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
```

Answer 200:

```json
{
  "activeAtOnce": 1,
  "dailyFree": 0,
  "usedToday": 0,
  "resetsAt": "2026-10-24T12:00:00.000Z"
}
```

Every refusal it may answer: `invalid_api_key` (401), `unauthenticated` (401), `account_stopped` (403), `email_unverified` (403), `plan_required` (403), `account_exists` (409), `email_refused` (422), `rate_limited` (429), `internal_error` (500), `auth_unavailable` (503).

---
This page: https://vecsnap.com/docs/api/account