---
title: "Export the credit ledger entry by entry"
method: GET
path: "/v1/credits/usage/entries"
---

# Export the credit ledger entry by entry

`GET /v1/credits/usage/entries`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/credits/usage/entries`
- Auth: HTTP bearer

Export the organization's credit ledger for a time window, newest first — one entry per metered inference call, for loading into your own warehouse and modelling cost per message, per agent, or per model.

**The unit is one metered call, not one message.** How many entries a single conversation turn produces depends on the engine that served it. Group by `traceId` to get the cost of a turn.

**Nothing is filtered out.** Entries Runbear does not bill for — memory updates, ambient runs, gating, context compaction — are included with `chargeable: false`, and entries with a `null` `traceId` are included too. Summing `credits` over the entries with `chargeable: true` for a billing period gives exactly the `currentUsageCredits` that `GET /v1/credits/usage` reports for it. That is the property to check your load against.

Pass `from` and `to` to bound the window; it may not exceed 31 days per request. Follow `nextCursor` until it is `null` to walk a window in full. History reaches back to the organization's first recorded usage — the ledger has no retention cutoff, and `traceId` reaches back with it.

## Query parameters

- `from` string, required: Start of the window to export (ISO 8601), inclusive. Required.
- `to` string, required: End of the window (ISO 8601), exclusive. Required.
- `limit` integer: Maximum number of entries per page (1–1000). Defaults to 500.
- `cursor` string: Opaque pagination cursor. Pass the `nextCursor` from the previous response. Omit on the first request.

## Response `200`

Default Response

- object
  - `entries` CreditUsageEntry[], required
    - `id` string, required: Stable identifier for this ledger entry.
    - `occurredAt` string, required: When the metered call was recorded (ISO 8601).
    - `traceId` string, nullable, required: Identifies the conversation turn this spend belongs to. Group entries by this field to get the cost of one turn. Treat it as an opaque grouping key — an entry carries either a 32-character OTel id or, from before that move completed in May 2026, a 36-character Langfuse id. The two never collide, and both group a turn. Resolvable through `GET /v1/agents/{agentId}/traces/{traceId}` within 90 days, though an entry from a Claude Agent SDK agent can answer 404: those traces go to a store that endpoint does not read. `null` on some entries recorded before 2026-09-18, whose path did not record the turn; every entry since carries one.
    - `agentId` string, nullable, required: The agent the spend is attributed to. `null` for usage not tied to one.
    - `model` string, required: Model that served the call.
    - `modelProvider` string, required: Provider of that model, e.g. `anthropic`, `openai`.
    - `byok` boolean, required: True when the call ran on your own provider key. Credits then cover Runbear's processing fee only, not the provider's inference charge — that one lands on your provider invoice instead.
    - `chargeable` boolean, required: False for inference Runbear performs and does not bill — every `usageContext` except `message` and `personal_agent`. These entries are included so the ledger is complete; only entries with `chargeable: true` count toward billed usage.
    - `usageContext` string, required: What produced the call. One of `message`, `personal_agent`, `memory_update`, `mcp_sub_agent`, `ambient`, `gating`, `compaction`.
    - `credits` number, required: Credits this entry consumed.
    - `creditsByTokenType` object, nullable, required: `credits` split by what consumed them, summing to `credits` exactly. `input` is the prompt the model was sent — including tool definitions and tool results, which are not metered separately. `cacheRead` and `cacheWrite` are prompt caching, and are where a growing conversation shows up. `output` is the reply. `null` for entries recorded before Runbear stored the split; it cannot be recovered from the total, because the price schedule and discount that produced it are not reconstructable after the fact.
      - `input` number, required
      - `cacheRead` number, required
      - `cacheWrite` number, required
      - `output` number, required
  - `nextCursor` string, nullable, required: Opaque cursor for the next page, or null once the window has been fully exported.

---

[API](https://skmtc.dev/runbear/apis/runbear-api.md) - [All operations](https://skmtc.dev/runbear/apis/runbear-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runbear/apis/runbear-api/revisions/c6a9c3066a5a?raw)