---
title: "Retrieve credit balance"
method: GET
path: "/credit"
tags: ["usage"]
---

# Retrieve credit balance

`GET /credit`

## Request

- Base URL: `http://localhost:3030`
- URL: `http://localhost:3030/credit`
- Auth: HTTP bearer

Returns the credit balance, the grants that make it up, and recent credits added or expired,
newest first.

Each entry includes `balance_after`, the balance once it applied.

## Query parameters

- `limit` integer: Number of ledger entries to return, between 1 and 500. Defaults to 50.

## Response `200`

The credit balance.

- CreditView
  - `object` 'credit_balance', required: The object's type. Always `credit_balance`.
  - `organization_id` string, required: The organization's id.
  - `balance` integer, required: The current credit balance.
  - `included_credits` integer, required: Credits included with the plan each billing period. `0` without a plan.
  - `grants` CreditGrant[], required: Grants with credits left to spend, in the order they are spent.
    - `object` 'credit_grant', required: The object's type. Always `credit_grant`.
    - `id` string, required: Unique identifier for the object.
    - `amount` integer, required: Credits granted.
    - `remaining` integer, required: Credits of the grant not yet spent.
    - `category` 'paid' | 'promotional', required: One of `paid` (a plan's period or a purchase) or `promotional` (signup or an adjustment).
    - `source` 'signup' | 'subscription' | 'purchase' | 'adjustment', required: One of `signup`, `subscription` (a plan's period), `purchase` or `adjustment`.
    - `priority` integer, required: Order of spending. Lower is spent first.
    - `effective_at` string, date-time, required: Time from which the credits can be spent.
    - `expires_at` string, date-time, nullable, required: Time at which what is left lapses. Null if it does not.
    - `created_at` string, date-time, required: Time at which the object was created.
  - `ledger` LedgerEntry[], required: The most recent credits granted, purchased, expired or adjusted, newest first, up to `limit`. Credits spent on requests are in `/usage`.
    - `delta` integer, required: Credits added, as a positive number, or spent, as a negative one.
    - `grant` string, nullable: The credit grant the credits were added to or taken from.
    - `reason` string, required: One of `signup`, `subscription`, `purchase`, `expiry` or `adjustment`.
    - `reference` string, nullable: The billing event's id for `purchase`, `subscription` and `expiry`. Null otherwise.
    - `balance_after` integer, required: The credit balance after this entry.
    - `created_at` string, date-time, required: Time at which the object was created.

## Other responses

- `401`: `credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.
- `422`: `parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.

---

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