Credits API

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, created under Settings → API keys (where available). If your organization doesn't show that item, open Settings → Members, which opens your organization's account page, and manage keys in its API Keys section; see 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#

The entry export answers 400 when to is not later than from ("to must be later than from."), when the window is longer than 31 days, or when cursor is not one the API issued.

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.

Reading the summary#

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 a handful of older entries 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.

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.

traceId is also the turn's id in the Traces API. To see what a turn did, pass it with the entry's agentId to GET /v1/agents/{agentId}/traces/{traceId} while the trace is inside the Traces API's 90-day retention. An older entry answers 404, and an entry from a Claude Agent SDK agent can too; the entry itself stays valid as a grouping key either way.

What drove the cost#

creditsByTokenType splits an entry's credits by what consumed them. The four parts sum to credits exactly.

Tool calls are not metered separately. A tool's definition and its result travel in the prompt, so their cost lands in input — a turn that called many tools shows up as a large input, not as its own line.

Watch cacheRead against input over time. A conversation that grows past the cache window stops reading from cache and starts paying full input rates for the same content, which is the usual reason a cost per message climbs without the traffic changing.

Reading the other fields#

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, and traceId reaches back with it.

Treat that id as opaque. Runbear moved tracing backends in May 2026, so an entry carries either a 32-character id or, from before that move completed, a 36-character one. The two never collide, and either groups a turn — which is what the field is for.

A small number of entries recorded before 2026-09-18 carry traceId: null, because the path that served the call did not record the turn. Every entry since carries one.

Related#

• Traces API — what an agent's turns actually did
• Authentication and API keys