Credits and usage

Mux is prepaid. Your account has one credit balance in US dollars, shared by all of your keys. These endpoints let you read it, add to it, and see where it went. The dashboard shows the same data: your balance on the overview page, spend over time and by model and key under usage, recent requests under activity, and purchases and grants under billing.

Except where noted, these endpoints accept either an API key or a management key, and always return data for the account the key belongs to.

Get your balance

GET /v1/credits

curl https://api.getmux.io/v1/credits \
  -H "Authorization: Bearer $MUX_API_KEY"

Credit pricing

GET /v1/credits/pricing

Public (no key needed). Returns the current purchase fee and the BYOK terms.

curl https://api.getmux.io/v1/credits/pricing

See Pricing for what these mean.

Add credits

POST /v1/credits/checkout

Creates a Stripe Checkout session for a credit purchase and returns its URL. Send the user there to pay. The credits are added to your balance automatically once the payment completes.

Field	Type	Description
`amount_usd`	number	Amount to charge, from 5 to 10,000.

curl https://api.getmux.io/v1/credits/checkout \
  -H "Authorization: Bearer $MUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 50}'

amount_usd is what you pay. credits_usd is what lands in your balance after the purchase fee (fee_usd). An amount outside 5 to 10,000 returns 400 invalid_request.

Ledger

GET /v1/credits/ledger

Every change to your balance, newest first.

Query parameter	Default	Description
`kind`	`purchase,grant,byok_fee`	Comma-separated list of entry kinds to include.
`limit`	`50`	Page size, 1 to 200.
`offset`	`0`	Entries to skip.

Entry kinds:

Kind	Meaning
`purchase`	Credits added by a purchase (after the fee).
`grant`	Credits added by Mux, for example a promotional grant.
`byok_fee`	A fee charged for a BYOK request past the free tier.
`usage`	The price of a search request.
`refund`	A charge refunded because the provider call failed.

By default the ledger shows money in and BYOK fees. Ask for per-request entries with kind=usage,refund.

curl "https://api.getmux.io/v1/credits/ledger?kind=purchase,grant&limit=20" \
  -H "Authorization: Bearer $MUX_API_KEY"

amount_usd is positive for credits added and negative for charges.

Usage

GET /v1/usage

Spend and request counts over a recent window, aggregated three ways. Only successful requests are counted.

Query parameter	Default	Description
`days`	`30`	Window length in days, 1 to 90.

curl "https://api.getmux.io/v1/usage?days=7" \
  -H "Authorization: Bearer $MUX_API_KEY"

daily has one entry per UTC day that had traffic. Days with no requests are omitted.
by_model and by_key are sorted by cost, highest first. Deleted keys still appear in by_key with their past usage.
Usage is recorded just after a request returns, so the newest requests can take a moment to appear.

Activity

GET /v1/activity

Your most recent requests, newest first.

Query parameter	Default	Description
`limit`	`50`	Page size, 1 to 200.
`offset`	`0`	Entries to skip.

curl "https://api.getmux.io/v1/activity?limit=2" \
  -H "Authorization: Bearer $MUX_API_KEY"

A successful request has the request id and status: "ok". Each upstream attempt that failed is logged as its own entry with status: "error", the reason in error, and a cost of 0, because failed attempts are refunded. A request that fell back to another model therefore shows an error entry followed by the successful one.