---
title: "Get credit balance"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Get credit balance

`GET /v1/usage`

## Request

- Base URL: `https://api.phototology.com`
- URL: `https://api.phototology.com/v1/usage`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-internal-secret`

Returns the authenticated user's spendable credit balance. `total` is the single number to show (community + purchased); effective spendable is `total - reserved`. The `community` / `purchased` split is retained for back-compat and refund-to-origin accounting: community credits (signup grant for new users; legacy monthly refill for accounts created before the pricing v1 cutoff), purchased credits (carry forward across months), and `reserved` credits currently held by in-flight analyze calls.

### Dual auth
Supports both Bearer API key (external callers) and `x-internal-secret` header plus `?userId=<id>` query param (server-to-server, for dashboard integrations).

## Query parameters

- `userId` string: User ID. Required only when using `x-internal-secret` auth.
- `tier` 'starter': Legacy tier query param. Only `starter` is valid; the Growth subscription tier was retired in 2026-05-17. The field is accepted for backward compatibility with phototology-web server actions that may still pass it; the response tier is always `starter`.

## Response `200`

Current credit balance for the authenticated user.

- object
  - `tier` string, required: API key tier. Historically `starter` or `growth`; the Growth subscription tier was retired in pricing v1 (2026-05-17) so this field now always returns `starter`. The field is kept in the response shape for SDK backward compatibility and may be removed in a future major version.
  - `total` integer, required: Single spendable credit balance (community + purchased). This is the number to show and reason about; effective spendable credit is `total - reserved`. Added 2026-05-29 (additive, non-breaking). The `community` / `purchased` split below is retained for back-compat and refund-to-origin accounting, not as two balances the holder manages.
  - `community` object, required
    - `balance` integer, required: Remaining community credits. Signup-grant landing pool: new accounts receive 1,000 for verifying an email (one-time, not recurring). The monthly auto-refill was retired in pricing v1 (cutover 2026-05-18).
    - `monthlyAllowance` integer, required: Legacy field. Was the monthly grant amount (e.g. 1,000 for starter). Reports 0 for accounts created after the pricing v1 cutoff (2026-05-18). Kept for backward compatibility.
    - `referralBonus` integer: Display-only lifetime referral earnings (cumulative credits a referrer has earned). NOT a spendable sub-balance: the actual referral grant lands in the purchased pool as spendable credit. Kept for backward compatibility.
    - `resetsInDays` integer, required: Legacy field. Was the days-until-monthly-refill counter. Reports 0 once the pricing v1 cutoff has bound the account. Relative integer (never an absolute timestamp). Kept for backward compatibility.
  - `purchased` object, required
    - `balance` integer, required: Remaining purchased credits. Carries over across months. Spent only after community pool is exhausted.
  - `reserved` integer, required: Credits currently held in reserve for in-flight analyze calls.

## Other responses

- `400`: Invalid tier or other validation failure on the internal-secret path.
- `401`: Missing or invalid auth (Bearer token rejected; `x-internal-secret` does not match).

---

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