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

# Credits

> How Kallima's credit system works — costs, monthly grants, top-ups, and transaction history.

Kallima uses a unified credit currency for all compute. Every pipeline job debits credits from your organization's balance. You start each month with a fresh grant based on your plan, and you can buy additional credits at any time.

## Check your balance

```bash theme={null}
curl https://api.kallima.bio/v1/me \
  -H "Authorization: Bearer $KALLIMA_API_KEY"
```

```json theme={null}
{
  "org_id": "aabbccdd-...",
  "plan": "team",
  "subscription_balance": 11840,
  "purchased_balance": 500,
  "total_credits": 12340,
  "monthly_grant": 12000
}
```

Credits come in two buckets:

| Bucket                 | Behavior                                                                                      |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `subscription_balance` | Monthly grant — refills on the first of each month, rolls over one month (capped at 2× grant) |
| `purchased_balance`    | One-time top-up packs — never expire                                                          |

Subscription credits are spent first; purchased credits are only used after the subscription bucket is empty.

## Credit costs

| Pipeline                     | Credits per job |
| ---------------------------- | --------------- |
| Humanization                 | 1               |
| Codon optimization           | 2               |
| Immunogenicity analysis      | 2               |
| Stability analysis           | 3               |
| Structure prediction         | 5               |
| Complex prediction (Boltz-2) | 25              |

Credits are debited at job submission. If a job **fails**, the cost is automatically refunded to your subscription bucket.

## Monthly grants by plan

| Plan      | Credits/month |
| --------- | ------------- |
| Free      | 30            |
| Starter   | 600           |
| Structure | 2,000         |
| Complete  | 5,000         |
| Team      | 12,000        |

Grants are applied lazily on the first API call of each calendar month. The rollover rule caps your subscription balance at **2× your monthly grant** — unused credits beyond that are not carried forward.

## Buying credits

Purchase one-time credit packs from the Dashboard → **Settings → Billing → Buy credits**. Packs are available in four sizes:

| Pack            | Credits | Price   |
| --------------- | ------- | ------- |
| Starter pack    | 500     | \$75    |
| Growth pack     | 2,500   | \$300   |
| Scale pack      | 10,000  | \$1,000 |
| Enterprise pack | 50,000  | \$4,000 |

Purchased credits appear in your balance immediately after checkout completes.

## Insufficient credits

If your balance is below the cost of the job you're submitting, the API returns:

```json theme={null}
{
  "type": "https://docs.kallima.bio/errors/insufficient_credits",
  "title": "Insufficient credits",
  "status": 402,
  "code": "insufficient_credits",
  "detail": "Structure prediction costs 5 credits. Buy a credit pack or upgrade your plan."
}
```

The job is not created and no credits are spent.

## Transaction history

Retrieve a paginated ledger of all credit activity (grants, spends, purchases, refunds) from the dashboard billing page or via the REST API:

```bash theme={null}
curl "https://api.kallima.bio/billing/credits/history?limit=20" \
  -H "Authorization: Bearer $KALLIMA_SESSION_TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "id": "txn-uuid",
      "kind": "spend",
      "amount": -5,
      "action": "structure",
      "job_id": "job-uuid",
      "subscription_balance_after": 11995,
      "purchased_balance_after": 500,
      "created_at": "2026-04-24T10:30:00+00:00"
    },
    {
      "id": "txn-uuid-2",
      "kind": "grant",
      "amount": 12000,
      "action": "monthly_grant",
      "job_id": null,
      "subscription_balance_after": 12000,
      "purchased_balance_after": 500,
      "created_at": "2026-04-01T00:00:01+00:00"
    }
  ],
  "has_more": true,
  "next_cursor": "c_eyJjIjoiMj..."
}
```

Transaction `kind` values:

| `kind`     | Meaning                                         |
| ---------- | ----------------------------------------------- |
| `grant`    | Monthly subscription credit applied             |
| `spend`    | Credits debited for a compute job               |
| `purchase` | Credits added via a credit pack checkout        |
| `refund`   | Credits returned after a failed or canceled job |

<Note>
  `GET /billing/credits/history` uses your dashboard session token (JWT), not an API token. It is not available on the `/v1/` API surface because credit history is a billing concern, not a programmatic integration concern. Use `GET /v1/me` from your API token to read the current balance.
</Note>