credits

Get the current credit balance of the account that pays for this credential's usage.

A Voyager sign-in in a workspace billed on Voyager reads the workspace's Voyager credits and plan (billing_product: "voyager"), its auto-reload (auto_reload) and its agent chat gate (chat); every other credential reads Moda's. upgrade_url is where that payer manages billing.

A balance that cannot be read answers 200 with plan: "unknown" and the payer's billing_product (unchanged for Moda clients, which always bill Moda). Only when the payer itself cannot be decided (a Voyager credential whose workspace switch is unreadable) is it a retryable 503 billing_unavailable: a Stripe blip is never read as "billed by Moda".

get/credits

Request

  • Base URL
    https://api.moda.app/v1
  • URL
    https://api.moda.app/v1/credits
  • Auth
    HTTP bearer

Headers

Moda-Version'2026-04-12' | '2026-05-01'
Example:2026-05-01

Calendar-dated API version pin. New integrations should pin 2026-05-01 to opt into the newest response shapes. For back-compat the server also accepts requests with no header and resolves them to the current default (today: 2026-04-12); that default advances on each sunset date. Any unsupported value returns 400 unsupported_version.

Response

Successful Response

credits_remaininginteger nullable

Current credit balance. Null if the billing service is unavailable or billing is not enabled for this account.

planstring nullable required

Current billing plan identifier (e.g. 'free', 'paid', 'ultra', 'enterprise'). Returns 'unlimited' when billing is not enabled. For a Voyager-billed workspace (billing_product 'voyager'), 'free', 'starter', 'creator', 'ultra' or 'gigamax', or null when it has no Voyager plan; its credits are Voyager credits (1 credit = 1 cent of provider cost).

credits_limitinteger nullable

Total credit allowance for the current billing period. Null if billing is not enabled.

credits_reset_datestring nullable

ISO 8601 date when credits reset for the current billing period. Null if billing is not enabled or reset date is unavailable.

billing_product'moda' | 'voyager' nullable

Whose credits these are: 'voyager' when this credential bills the workspace's Voyager account, otherwise 'moda'. Remedies (upgrade_url) follow it.

billing_org_idstring nullable

The organization that pays.

upgrade_urlstring nullable

Where the payer manages billing.

min_hold_creditsinteger nullable

What a provider-proxy generation nothing prices holds before it runs, in this payer's credits: 1 for a Voyager-billed workspace, whose every other hold is the job's expected cost (its request-sized price, or the endpoint's median settled charge), and Moda's floor (300) otherwise (an unpriced Moda video holds 750, capped at five times its dearest settled charge when it has one to four).

credits_per_usdinteger nullable

Credits this payer is charged per dollar of provider cost, as settlement converts it: 100 for a Voyager-billed workspace, and for Moda the plan's rate (100 for a paid plan in the credit-discount experiment, 300 otherwise). Null when the payer or plan could not be read.

effective_dollars_per_creditnumber nullable

Estimated user USD per credit for billing_product/billing_org_id, distinct from provider accounting credits_per_usd. While plan/bonus credits remain, selected per-seat list price divided by monthly included credits (annual price / 12 first); otherwise pack price $0.011. Discounts, coupons and comps are not applied. Voyager Free uses $0.01 by convention; Moda uses its configured purchase rate. Null when unavailable: consumers must not infer zero cost or bypass spend confirmation. Advisory base rate, not a blended quote across grant boundaries.

effective_dollars_per_credit_source'plan' | 'pack' | 'free' | 'moda' | 'unknown'

Source of the effective user purchase rate; unknown when unavailable.

effective_dollars_per_credit_upper_boundnumber nullable

Maximum configured Individual/Team monthly and annual-per-month credit purchase rate, including packs. Present only with configured_tariff proof and an unavailable actual rate. An upper estimate, never the actual rate or a commercial ceiling; actual effective_dollars_per_credit remains authoritative when known.

effective_dollars_per_credit_upper_bound_source'voyager_catalog_max' nullable

Provenance of the validated upper estimate; null without configured tariff proof.

configured_tariffboolean

True only when this payer's selected immutable plan price ID, USD amount, currency and interval match the canonical purchasable catalogue. When the actual effective rate is unavailable, this proof permits a catalogue-derived maximum estimate. False or absent is no proof; plan names, offline state and missing rates cannot establish it. A known effective rate remains authoritative.

internalboolean nullable

Voyager-billed only (null otherwise, or when unreadable): the workspace's plan is a comped internal one (100% off, overage and chat included), as on the dashboard's billing status, and the caller holds a seat on it: false for a member without one (refused no_voyager_seat; chat.seated is false).

overage_enabledboolean nullable

Voyager-billed only (null otherwise). Voyager credits are prepaid, with no overage: false for every paying workspace. True only for a comped internal plan, which may run its internal allowance below zero. Kept for older desktop builds.

overage_remaining_creditsinteger nullable

Voyager-billed only: 0 for every paying workspace (prepaid, no overage); a comped internal plan's remaining internal allowance. Null for a Moda-billed workspace or when unreadable.

plan_status'active' | 'none' | 'unavailable' nullable

Voyager-billed only (null otherwise): 'active' when the workspace has a Voyager plan, 'none' when Stripe answered that it has none, 'unavailable' when the plan could not be read right now (never reported as no plan). With 'unavailable', plan is 'unknown' and the plan-derived fields are null; credits_remaining is still the balance when the credit ledger keeps it.

free_plan_refusedboolean nullable

Voyager-billed with no plan only (null otherwise, or when unreadable): true when this workspace would be refused the Free plan now because its creator (or this person) already has Free in another workspace, so a client says it has no plan instead of 'setting up your free plan'; false otherwise.

free_plan'pending' | 'refused' nullable

Voyager-billed with no plan only (null otherwise, with the Free plan off, or when unreadable): whether the Free plan is still coming. 'refused' when it will not: the case free_plan_refused names, or a recorded denial or revocation that is not due for a recheck (it was decided, or re-judged and denied again, within the hour); a client says the workspace has no plan. 'pending' when it may: undecided, or a recheck is due.

trialingboolean nullable

Voyager-billed only (null otherwise, with no plan, or when unreadable): the workspace's Voyager plan is in its trial, so a client can say so before the first paid generation.

trial_ends_atstring nullable

ISO 8601 end of the Voyager plan's trial while trialing; null otherwise.

Changes

    • breaking

      response property plan list-of-types was widened by adding types null to media type application/json of response 200

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status