# Credits API

> Read your organization's credit usage, from the period total down to individual metered calls.

Source: https://docs.runbear.io/api/credits

Last updated: 2026-09-18

The **Credits API** reports what your organization has spent, at three resolutions of the same number. Use it to pull Runbear usage into your own finance tracking or warehouse, forecast spend, and find which agents and models drive it.

Authenticate with a bearer API key from **Settings → API Keys**. These are organization-level endpoints, so an agent-scoped key is refused. Full request and response schemas live in the [OpenAPI reference](https://api.runbear.io/v1/docs).

## Endpoints

| Endpoint                        | Resolution                                              |
| ------------------------------- | ------------------------------------------------------- |
| `GET /v1/credits/usage`         | The current billing period, as one summary              |
| `GET /v1/credits/usage/periods` | The same summary for every billing period, newest first |
| `GET /v1/credits/usage/entries` | Every metered call, newest first                        |

## The three fit together

The summary tells you where the period stands: credits included in the plan, the overage allowance, and usage so far. The period list gives you the same shape for every period you have, so you can track usage period over period. The entry export gives you the rows those totals are built from.

Start at the summary. Drop to the entries when you need to know *why* a period looks the way it does.

The period list includes the period still running, not only finished ones. That entry carries `isCurrent: true` and matches `GET /v1/credits/usage` exactly; on a walk that starts with no cursor it is the first entry of the first page. Its figures are still moving, so exclude it when you chart completed periods, and do not add it to the summary — it *is* the summary. Every other entry has ended and its usage is final.

### Only usage is historical

Runbear does not snapshot your plan configuration per period. On a past period's entry, `currentUsageCredits` is what that period actually consumed, but the allowance fields beside it — `planIncludedCredits`, `complimentaryCredits`, `includedCredits` and `overageLimitCredits` — describe your plan **as it stands today**, not as it stood then. `overageCreditsUsed` is derived from the historical usage against today's allowance, so it is a mix of the two.

> **Warning**
>
> If your plan changed, a past period will report an allowance it never had. Treat `currentUsageCredits` as the historical fact and store your own allowance figures alongside it if you need the period's real budget. Charting `overageCreditsUsed` across a plan change will show overage that was never incurred.

## The numbers reconcile

Sum the `credits` of every entry with `chargeable: true` over a billing period, and you get exactly the `currentUsageCredits` that `GET /v1/credits/usage` reports for it.

Check your load against that. It is the property the export is designed around, and a mismatch means the load dropped rows rather than that the figures disagree.

The export never filters. Calls Runbear performs and does not bill for come back with `chargeable: false` — everything except `message` and `personal_agent` — and entries that predate trace recording come back with `traceId: null`. Leaving either out is what would break the sum.

## One entry is one metered call

An entry is one metered call to a model, not one message. How many entries a single conversation turn produces depends on the engine that served it.

Group entries by `traceId` to get the cost of a turn. That is the same id the [Traces API](/api/traces.md) serves, so an expensive turn can be looked up directly:

```
GET /v1/agents/{agentId}/traces/{traceId}
```

A turn is not uniform. Context compaction inside a turn runs on a different model and is not chargeable, so a turn's entries can differ in `model` and in `chargeable`.

## Reading the other fields

| Field                    | What it tells you                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `agentId`                | Which agent the spend belongs to. `null` when it is not tied to one                                                             |
| `model`, `modelProvider` | What served the call — for comparing cost across models                                                                         |
| `byok`                   | Whether the call ran on your own provider key                                                                                   |
| `usageContext`           | What produced the call. One of `message`, `personal_agent`, `memory_update`, `mcp_sub_agent`, `ambient`, `gating`, `compaction` |

> **Entries on your own key**
>
> When `byok` is `true`, the credits cover Runbear's processing fee only. The provider's inference charge for that call lands on your own provider invoice, not here. To model total inference cost, add your provider's bill to these figures for the agents you have moved to your own key.

## What credits do not include

Credits measure token usage and nothing else. Your plan fee is not spread across messages, so you will not find it in any entry — it stays a separate, contracted number. Separating the two is the point: the entries are your variable cost, and the plan fee is your fixed one.

## Limits

`from` and `to` are required on the entry export, and the window between them may not exceed 31 days. Request a longer history as consecutive windows.

Pages return up to 1000 entries. Follow `nextCursor` until it is `null` to walk a window in full.

The ledger has no retention cutoff and reaches back to your organization's first recorded usage. `traceId` is newer: Runbear began recording it in September 2026, so entries older than that carry `null` there and cannot be grouped into turns.

## Related

- [Traces API](/api/traces.md) — what a turn actually did, looked up by `traceId`
- [API keys](/api/api-keys.md)