---
title: "Get Studio Credit balance and what each operation costs."
method: GET
path: "/credits"
tags: ["Credits"]
---

# Get Studio Credit balance and what each operation costs.

`GET /credits`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/credits`
- Auth: HTTP bearer

Read-only summary of the current Studio Credit balance, monthly bucket allocation/use, and perpetual credit balance, plus `costs`: what each operation costs, the same list the Billing page shows (each line names the ledger `ops` its charges carry) — and the ledger behind the number: `usage` (what the credits actually WENT TO, each charge named the way the Billing page names it, with the screenplay it was spent on; grants and refunds are shown but are not spending), `usageGroups` (repeated charges on one project on one UTC day folded into one entry, as the Billing page shows them) and `held` (the credits the writer's work is HOLDING right now — reserved for jobs still in flight, not yet spent or given back — with `heldTotal` summed over EVERY hold, `heldCount` and a plain `heldNote`). `credits.billing` is how credits are bought: the saved top-up card, this month's spend against the monthly spending cap, auto top-up and `topupUrl` (buying happens only in the app; set auto top-up and the cap with PATCH /credits/billing). `?recent=N` caps the two activity pages (default 10, max 30; 0 omits both pages); the balance and the price list are never capped. A pitch deck is priced by the second: 1 credit a second to render at 480p, plus 1 credit a second to finish at 720p (2 credits a second in all; a 1080p finish is 4 credits a second instead). Planning is free. The exact price is quoted per shot once the plan is ready, before anything renders; location plates and on-screen text are itemized in the same quotes. A trailer is priced by the second: 1 credit a second to render at 480p, plus 1 credit a second to finish at 720p (2 credits a second in all; a 1080p finish is 4 credits a second instead). Planning is free. The exact price is quoted per shot once the plan is ready, before anything renders; location plates and on-screen text are itemized in the same quotes. Use this before submitting expensive generation jobs so agents can short-circuit with `insufficient_credits` guidance instead of triggering reservations.

## Query parameters

- `recent` integer

## Response `200`

Credit summary.

- CreditsSummary
  - `costs` StudioCreditCost[], required: What each operation costs, in the order the Billing page lists them — the same list the UI shows. A flat price has `per: null`; a rate names its unit in `per` and is quoted by the operation before anything is reserved.
    - `key` 'TABLE_READ_SHORT' | 'TABLE_READ_LONG' | 'TABLE_READ_REFINE' | 'TABLE_READ_REVOICE' | 'IMAGE' | 'VOICE' | 'VOICE_CLONE_PRO' | 'VIDEO_RENDER_480P' | 'VIDEO_RENDER_720P' | 'VIDEO_RENDER_1080P' | 'VIDEO_FINISH_720P' | 'VIDEO_FINISH_1080P' | 'TAKE_REPAIR' | 'TEXT_LAYER' | 'SCREEN_CAPTURE', required: The price line.
    - `group` 'Table reads' | 'Pictures and voices' | 'Video', required: The heading the Billing page lists it under.
    - `label` string, required
    - `credits` number, required: The price in Studio Credits per `per`.
    - `per` string, required: The unit one `credits` buys: `read`, `image`, `voice`, `second`, `layer`… An operation prices its units before anything is reserved.
    - `note` string, required
    - `ops` string[], required: The ledger op keys (`opKey`) its credit transactions carry. An op can cover several lines: every cast picture and voice is booked `VISUALIZATION`, every line of a deck `PITCH_DECK`.
  - `credits` object, required
    - `balance` integer, required: Total Studio Credits available: carried-over plan credits, this month's plan credits and top-ups (`carriedBalance + monthlyBucketRemaining + perpetualBalance`).
    - `monthlyBucketAllocated` integer, required
    - `monthlyBucketUsed` integer, required
    - `monthlyBucketRemaining` integer, required
    - `perpetualBalance` integer, required
    - `cycleStartedAt` string, date-time, nullable, required
    - `cycleExpiresAt` string, date-time, nullable, required
    - `carriedBalance` integer, required: Unused plan credits carried over from earlier months, still spendable. Spent first (soonest to expire first), before this month's plan credits and top-ups.
    - `carried` object[], required: Each carried batch with credits left, soonest to expire first. A batch lasts two renewals beyond the month it was granted in, and only while the subscription stays active.
      - `credits` integer, required
      - `expiresAt` string, date-time, required
    - `carryCap` integer, required: The most carried credits can come to: two months of the plan's monthly credits (0 with no plan).
    - `carriesAtRenewal` integer, required: What would carry into next month at the next renewal if nothing more were spent: what is left of this month's plan credits, up to the cap.
    - `breakdown` string, nullable, required: How `balance` splits, in the words the Billing page shows under it: what is left this month, what carried over, how much can carry into next month, when the plan resets, and any top-up, e.g. "4,031 left this month · 1,200 carried over · up to 4,031 carry into next month · resets 2026-11-11 · 50 top-up, never expires". Null when there is nothing to split (a free account with nothing bought).
    - `carryNote` string, nullable, required: The rollover rule in the Billing page's one sentence; null with no plan.
    - `billing` CreditBilling, required: How credits are bought. Auto top-up adds one pack whenever the balance falls below a threshold, charged to the account's saved top-up card, and only within the monthly spending cap (whole US dollars charged for credits per UTC calendar month, net of refunds, counting every pack bought on the Billing page and every automatic top-up, and an attempt still being paid; the plan itself is not counted). A refunded automatic top-up turns auto top-up off. Turning it on needs a saved card (saved in the app for $0, or by a top-up; send the writer to `fixUrl` when there is none), a plan that allows top-ups and a cap of at least the pack price; the threshold must be below the pack's credits. Buying credits happens only in the app: send the writer to `topupUrl`.
      - `card` object, nullable, required: The saved top-up card (brand, last 4, expiry), which one-tap and auto top-up charge. Saved in the app with no charge, or by a top-up; null until one is saved.
        - `brand` string, required: e.g. `visa`.
        - `last4` string, required
        - `expMonth` integer, nullable, required
        - `expYear` integer, nullable, required
      - `spendCap` object, required: The monthly spending cap: whole US dollars charged to a card for credits per UTC calendar month, net of refunds (the plan itself is not counted).
        - `capUsd` integer, nullable, required: The cap the writer set, or null for none.
        - `spentUsd` number, required: Charged (or being charged) for credits so far this month.
        - `from` string, date-time, required
        - `resetsAt` string, date-time, required: The 1st of next month, 00:00 UTC.
      - `autoTopup` object, required
        - `enabled` boolean, required
        - `thresholdCredits` integer, nullable, required: When the balance falls below this…
        - `packKey` 'PACK_10' | 'PACK_25' | 'PACK_50' | 'PACK_75' | 'PACK_100' | 'null', nullable, required: …this pack is added.
        - `packUsd` integer, nullable, required
        - `packCredits` integer, nullable, required
        - `offReason` 'authentication_required' | 'card_declined' | 'card_removed' | 'dispute' | 'plan_ended' | 'refunded' | 'null', nullable, required: Why auto top-up turned itself off (null while on, or when the writer turned it off).
        - `offAt` string, date-time, nullable, required
      - `topupUrl` string, uri, required: Where the writer buys credits: the app's Billing page with the pack's top-up open. No API call buys credits.
  - `usage` StudioCreditActivityLine[], required: What the credits actually WENT TO, newest first: each charge named the way the Billing page names it, with the screenplay it was spent on. Grants and refunds are included as ledger lines but are not spending. `?recent=N` caps the page (default 10, max 30); 0 omits it.
    - `id` string, required: The ledger line's id.
    - `delta` integer, required: Negative for spending or a hold, positive for a grant or a refund of credits.
    - `reason` string, required: The ledger reason: `RESERVE` (held), `CONSUME_PROVISION` (settled: spent), `RELEASE` (returned), or a grant/refund reason.
    - `label` string, required: How the Billing page names this line, in the writer's words.
    - `opKey` string, nullable, required: The ledger op key this line was booked under, when it is a charge.
    - `feature` string, nullable, required
    - `quantity` integer, nullable, required
    - `unitCredits` number, nullable, required
    - `scriptTitle` string, nullable, required: What this line was for, by name: the screenplay it was spent on, or — for a hold placed before the screenplay exists, or a picture or voice made for a project — the episode plan, the deck or trailer, or the project. Null only for a grant or adjustment that went on no work.
    - `projectName` string, nullable, required: The project the line's work belongs to, by name; `usageGroups` folds repeated charges by it. Null for a grant or a line on no project.
    - `createdAt` string, date-time, required
  - `usageGroups` object[], required: Repeated charges folded the way the Billing page's Recent activity folds them: two or more `usage` lines with the same project, name, ledger reason and UTC day (a recurring show's nightly table reads) as one entry, newest first. A single charge, a grant and a line on no project are not grouped; read them in `usage`.
    - `projectName` string, required: The project the charges were for.
    - `label` string, required: The charges' shared name, as `usage` names each.
    - `reason` string, required: The ledger reason they share.
    - `day` string, date, required: The UTC day they fall on.
    - `count` integer, required
    - `delta` integer, required: The lines' deltas summed.
    - `text` string, required: The group in the Billing page's words, e.g. "HNRadio · Table read × 12".
    - `amount` string, required: The summed amount as the Billing page says it ("-240", "80 held").
    - `lineIds` string[], required: The `usage` line ids folded in, newest first.
  - `usageCount` integer, required: How many ledger entries this writer has in TOTAL across EVERY page (not just the `usage` page here). With the page length it names "N of M entries shown", whenever more exists.
  - `heldTotal` integer, required: The credits the writer's work is HOLDING right now, summed over EVERY hold — not just the `held` page. What is not spent comes back.
  - `heldCount` integer, required: How many holds are tying up those credits.
  - `held` StudioCreditActivityLine[], required: One line per hold: credits reserved for work still in flight (not yet spent or given back), newest first, named the same way as `usage`.
    - `id` string, required: The ledger line's id.
    - `delta` integer, required: Negative for spending or a hold, positive for a grant or a refund of credits.
    - `reason` string, required: The ledger reason: `RESERVE` (held), `CONSUME_PROVISION` (settled: spent), `RELEASE` (returned), or a grant/refund reason.
    - `label` string, required: How the Billing page names this line, in the writer's words.
    - `opKey` string, nullable, required: The ledger op key this line was booked under, when it is a charge.
    - `feature` string, nullable, required
    - `quantity` integer, nullable, required
    - `unitCredits` number, nullable, required
    - `scriptTitle` string, nullable, required: What this line was for, by name: the screenplay it was spent on, or — for a hold placed before the screenplay exists, or a picture or voice made for a project — the episode plan, the deck or trailer, or the project. Null only for a grant or adjustment that went on no work.
    - `projectName` string, nullable, required: The project the line's work belongs to, by name; `usageGroups` folds repeated charges by it. Null for a grant or a line on no project.
    - `createdAt` string, date-time, required
  - `heldNote` string, required: A plain sentence for the writer: what is held and that what is not spent comes back, or that nothing is holding credits right now.

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/86e084144cef?raw)