Credits API
Read your organization's credit usage, from the period total down to individual metered calls.
On this page
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.
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.
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 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 |
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 — what a turn actually did, looked up by
traceId - API keys