---
title: "Get the AI credit balance"
method: GET
path: "/api/v1/credits"
tags: ["Subscription"]
---

# Get the AI credit balance

`GET /api/v1/credits`

## Request

- Base URL: `https://www.poster.ly`
- URL: `https://www.poster.ly/api/v1/credits`
- Auth: HTTP bearer

Return the AI credit wallet the authenticated key can spend from: credits available now, the monthly included allowance and how much of it is used, purchased pack balance, plan tier, and when the included pool next resets. Credits are a shared WORKSPACE wallet owned by the billing owner, and every active member draws the same pool. This endpoint reports that wallet, not a personal figure, so a member key sees the balance it can actually spend. `workspace.role` reports the caller role. Requires the `billing:read` scope. Bypasses the API add-on paywall so a user can always inspect their own balance. Returns 503 `wallet_unavailable` if the wallet lookup degrades, rather than reporting a misleading zero balance.

## Response `200`

Credit balance fetched successfully.

- CreditsSummaryResponse
  - `credits` object, required
    - `available` integer, required: Credits spendable right now: included remaining plus purchased balance.
    - `included` object, required
      - `monthly` integer, required: Included credits granted per billing period for the plan tier.
      - `used` integer, required: Included credits consumed so far this period, across all active workspace members.
      - `remaining` integer, required
    - `purchased_balance` integer, required: Credits bought in packs. Spent only after the included pool is exhausted.
    - `plan_tier` string, required
    - `is_trial` boolean, required
    - `period_start` string, date-time, required
    - `resets_at` string, date-time, nullable, required: Next included-pool reset. Null while trialing (one-time grant) or on a plan with no included pool.
    - `workspace` object, required
      - `role` string, required: Caller role in the active workspace.
      - `shared_wallet` boolean, required: Always true: the wallet belongs to the workspace billing owner and every active member draws it.

## Other responses

- `401`: Invalid or missing API key
- `403`: Request is authenticated but not allowed
- `429`: Too many requests

---

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