> ## Documentation index
> Fetch the complete documentation index at: https://docs.leadmcp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get credit balances

`GET /credits`

Returns both meters, contact credits and premium credits, as separate objects. Premium credits pay for engagers and verified emails. Stored contact delivery uses contact credits. When a premium unit finds no room, the API answers `402 premium_credits.exhausted` with the reset time and an `upgrade_url` for the account owner. Free.

Returns both meters, contact credits and premium credits, as separate objects. Premium credits pay for engagers and verified emails. Stored contact delivery uses contact credits. When a premium unit finds no room, the API answers `402 premium_credits.exhausted` with the reset time and an `upgrade_url` for the account owner. Free.

Cost: Free.

## Response

- `contact_credits` | ContactCreditBalance | required.
  - `contact_credits_per_month` | integer | required. The monthly contact credit cap of the plan. On the paid plan, the cap the Fair Usage Policy sets. On the free plan, the lifetime pool: 1,000 contact credits in total, for the life of the account.
  - `contact_credits_per_day` | integer | required. The daily contact credit cap of the plan. On the paid plan, the cap the Fair Usage Policy sets. On the free plan, the same lifetime pool as `contact_credits_per_month`.
  - `month_remaining` | integer | required. The contact credits left in the current billing month. A paid plan's month starts on its billing date each month; without a subscription it is the UTC calendar month. On the free plan, the contact credits left in the lifetime pool; the pool has no window.
  - `today_remaining` | integer | required. The contact credits left in the current UTC day. On the free plan, the same number as `month_remaining`.
  - `binding` | enum | required. The window that runs out first at the current pace. On the free plan, always `month`. Values: `month`, `day`.
  - `resets_at` | string | required. The RFC 3339 UTC time at which the binding window resets. On the free plan the pool never resets, and the field is `9999-12-31T23:59:59.000Z`.
- `premium_credits` | PremiumCreditBalance | required. This month's premium credits. Premium credits pay for engagers and verified emails, and reset on the billing date each month.
  - `allowance` | integer | required. The premium credits the plan grants this month, plus any grant that arrived this month.
  - `used` | integer | required. The premium credits spent this month on delivered premium units.
  - `held` | integer | required. The premium credits running work holds before it delivers. A hold settles to what was delivered or is released.
  - `available` | integer | required. The premium credits a new premium unit can take right now: the allowance less used and held, never below zero.
  - `resets_at` | string | required. The RFC 3339 UTC time at which the allowance resets: the next billing date, or the start of the next UTC month without a subscription.

## Failures

| Status | Meaning |
| --- | --- |
| `401` | The credential is missing, unknown or revoked. |
| `429` | The key passed 300 requests a minute or 2 concurrent requests. |
| `503` | The data is unavailable for a short time. |

## Example

```bash
curl -sS "https://api.leadmcp.ai/v1/credits" \
  -H "Authorization: Bearer lm_live_YOUR_API_KEY" \
  -H "LeadMCP-Version: 2026-09-19"
```

Response `200`:

```json
{
  "ok": true,
  "request_id": "req_01JBQ2W8K9V6M3T0X5Y7Z4A1BC",
  "release": "b_2026_09_15",
  "data": {
    "contact_credits": {
      "contact_credits_per_month": 1000,
      "contact_credits_per_day": 1000,
      "month_remaining": 950,
      "today_remaining": 950,
      "binding": "month",
      "resets_at": "9999-12-31T23:59:59.000Z"
    },
    "premium_credits": {
      "allowance": 0,
      "used": 0,
      "held": 0,
      "available": 0,
      "resets_at": "2026-10-01T00:00:00Z"
    }
  },
  "quota": {
    "plan": "free",
    "contact_credits_used": 50,
    "month_remaining": 950,
    "today_remaining": 950,
    "binding": "month",
    "resets_at": "9999-12-31T23:59:59.000Z"
  },
  "warnings": []
}
```