# Usage and credits

Every model call costs credits. If your integration runs AI at any volume, plan for
reaching the limit and for seeing it coming.

## Check the balance

`GET /me` carries the current balance, which makes it the cheapest pre-flight check
before a batch of expensive work:

```json
{
  "credits": {
    "available": 50000,
    "used": 1284,
    "remaining": 48716,
    "hasCredits": true,
    "low": false
  }
}
```

`low` is the warning to act on. It fires before `hasCredits` goes false, which is the
difference between slowing down and stopping.

## Running out

When credits are exhausted, model-running endpoints answer **403** with
`code: "insufficient_credits"`:

```js
if (err.code === "insufficient_credits") {
  await pauseQueue();      // topping up is a billing action, not an API one
  notifyOperator();
} else if (err.code === "license_required") {
  // the plan doesn't include this module at all; a top-up won't help
}
```

The two are different problems sharing a status. `insufficient_credits` is temporary and
fixed by topping up, while `license_required` means the plan does not include that module
and no amount of credit changes it. Retrying either is pointless. See [errors](/errors).

Credits are not the only cap. Model-running endpoints are also counted against the
`expensive` [rate-limit tier](/rate-limits), so a burst can hit a 429 while credits are
healthy. Handle both.

## Usage against the plan

```
GET /usage/summary
```

Reports what has been consumed this cycle and what the plan allows, the numbers behind a
usage bar:

| Field | |
|---|---|
| `availableCredits`, `currentPeriodUsage`, `remainingCredits` | The cycle's credit position. |
| `creditsExceeded` | Whether the cycle is spent. |
| `topupCredits` | Purchased credits held on top of the plan. **Plan credits burn first**, so this is the tail of the bar rather than a separate pool. |
| `creditsCycle` | `monthly` or `annual`. Annual plans grant credits yearly. |
| `storageUsed`, `storageEntitlement` | Bytes. Storage is entitled separately from credits. |
| `accountCreated` | For building a period selector that does not offer periods before the workspace existed. |

This endpoint needs only `usage:view`, so an ordinary integration can watch its own
consumption. The breakdowns below sit under `/admin` and need `admin:usage:view`.

## Usage breakdowns

Three views over the same data, for three different questions.

**`GET /admin/usage/entries`** lists the individual metered operations: what was run, by whom,
and how many credits it cost. Paginated with the standard [envelope](/pagination).

**`GET /admin/usage/aggregated`** returns totals rather than rows.

**`GET /admin/usage/pivot`** groups totals two ways at once, for a table:

```
GET /admin/usage/pivot?group_by=usage_user&time_granularity=week&tz=America/New_York
```

`group_by` accepts `date`, `usage_user`, `agent_name`, `prompt_name` or `usage_param`,
and `time_granularity` is `day`, `week` or `month`. Pass `tz`, or the buckets fall on
someone else's day boundaries.

**`GET /admin/usage/details`** returns the entries behind one cell of that pivot. This is the
drill-down: when a number looks wrong, open it to see the calls that produced it.

### Shared filters

These endpoints share `usage_user`, `usage_param`, `usage_timestamp` (a time range) and
`usage_details`, plus `agent_id` and `prompt_id` on the detail view. One is worth calling
out:

<Callout type="note">
**`usage_user=null` is a real query, not an empty filter.** The literal string
`null` matches entries with no user attached: scheduled work, autopilot runs,
anything the platform did on its own. Omitting the parameter returns every user's
rows instead, which is a different question with a similar-looking answer.
</Callout>

That bucket is where [autonomous](/autonomous-ai) work appears. If usage climbed
overnight and no user accounts for it, run that query.

## Attribute spend

Usage entries carry the agent and prompt that produced them, which makes per-feature
accounting possible without instrumenting your own side:

```
GET /admin/usage/pivot?group_by=agent_name&time_granularity=month
```

This is the administrative view, so the key needs `admin:usage:view`. For an integration
reselling AI or billing its own customers, that grouping plus `usage_user` is the raw
material for an invoice.

## What spends credits

Anything that runs a model. These are the easiest to underestimate:

| | |
|---|---|
| `POST /threads/{id}/messages` | Every message, and every tool call it makes. |
| `POST /files/{id}/reanalyze` and the bulk form | Per file. Re-analyzing a library is a real bill. |
| Generation | Images, infographics, decks. See [generating content](/generating-content). |
| `POST /tasks/{id}/run-autopilot` | Per run, and routines run unattended on a schedule. |
| The `/assist/*` helpers | One call each. |

Two of these deserve a budget alarm rather than a spot check, because nobody is watching
when they fire: scheduled routines and scheduled infographic refreshes. A weekly refresh
across forty infographics is roughly five hundred model calls a quarter that nobody
requested individually.

## Next steps

- [Plans and modules](/plans-and-modules) explains what your plan entitles.
- [Autonomous AI](/autonomous-ai) covers the work that spends credits unattended.
- [Rate limits](/rate-limits) is the other ceiling on model calls.

<Callout type="note">
	The product guide covers the same subject from the app's side: [the usage screens, and the four habits that prevent most credit surprises](/guide/admin/usage-and-credits).
</Callout>