---
title: "Get credit balance"
method: GET
path: "/credits/balance"
tags: ["Credits"]
---

# Get credit balance

`GET /credits/balance`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/credits/balance`
- Auth: HTTP bearer

Read the organization credit position. `prepaid_credit` is the prepaid usage credit (redeemed credit codes and granted credit) that can still pay for usage. `budget` is always null: agent spending budgets were retired, and the field is kept for existing clients. Amounts are strings of integer micros (1 USD = 1000000 micros).

## Response `200`

The organization credit balance.

- object
  - `success` true, required
  - `data` CreditBalance, required
    - `budget` object, nullable, required: Always null. Agent spending budgets were retired; the field is kept so existing clients keep working.
      - `currency` string, required: Currency of the budget, for example `usd`.
      - `max_amount_micros` string, required: Total allowance the operator funded, in micros.
      - `spent_micros` string, required: How much of the allowance has been drawn down, in micros.
      - `remaining_micros` string, required: `max_amount_micros - spent_micros`, floored at zero.
      - `per_topup_cap_micros` string, nullable, required: Largest single top-up allowed, in micros, or null for no per-top-up cap.
      - `expires_at` string, date-time, nullable, required: When the allowance expires, or null for no expiry.
      - `status` string, required: Budget status. An active budget reads `active`.
    - `prepaid_credit` object, nullable: Prepaid usage credit (redeemed credit codes and granted credit) that can still pay for usage. Null when there is none. Omitted when an exact figure cannot be given right now; the rest of the balance is still returned.
      - `currency` string, required: Currency of the credit, which is the organization billing currency.
      - `remaining_micros` string, required: What the credit can still pay for, in micros.
      - `next_expires_at` string, date-time, nullable, required: Earliest expiry among credits with a balance, or null when none of them expires.

## Other responses

- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

## Changes

> 32 revisions in range; 1 not diffed.

- **2026-11-03** `bce409c97acb`: 93 warning
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `401`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `403`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `429`
  - added the new `builtin_role` enum value to the `error/code` response property for the response status `401`
  - …89 more
  - …this revision’s changelog is incomplete
- **2026-10-21** `0360ea8d4f3d`: 39 warning
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `401`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `403`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `429`
  - added the new `agent_limit` enum value to the `error/code` response property for the response status `401`
  - …35 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/primitive/apis/primitive-api/changes/credits/balance/get.md)

---

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