---
title: "Get the credit balance"
method: GET
path: "/v1/billing/balance"
tags: ["Billing"]
---

# Get the credit balance

`GET /v1/billing/balance`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/billing/balance`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://recruitmcp.com/oauth/authorize`, token URL `https://recruitmcp.com/oauth/token`, scopes: `account:read`)

Account balance by source. A customer-bound key receives that customer's remaining daily cap, or null when the customer has no cap. It does not receive the account pool, buckets, or subscription.

Scope: `account:read`.

## Headers

- `RecruitMCP-Version` '2026-10-13'
- `RecruitMCP-Customer` string

## Response `200`

Balance.

- Balance
  - `balance_credits` integer, nullable, required: Account balance. A customer-bound key gets that customer's remaining daily cap, or null when the customer has no cap.
  - `by_source` object: plan, topup, free, promo (launch bonus), admin, refund, legacy. Empty for a customer-bound key.
  - `buckets` object[]
  - `upcoming_expiries` object[]
    - `expires_at` string, date-time
    - `credits` integer
    - `source` string
    - `bucket_id` string
  - `next_expiry` object, nullable
    - `expires_at` string, date-time
    - `credits` integer
  - `rules` object
  - `subscription` object, nullable

## Other responses

- `400`: `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `401`: `unauthorized` (do not retry): Missing bearer API key.
- `403`: `forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.
- `429`: `rate_limited` (retry): Per-key rate limit exceeded.

## Changes

- **2026-10-20** `ad27b35513a6`: 4 warning
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `401`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `403`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `429`

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/billing/balance/get.md)

---

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