Limits, credits and plans

Rate limits and the headers that report them, what a credit is, and what a plan changes.

Three independent limits, for three different problems: how fast you call, how much you call in a day, and how many transcriptions you have running at once.

The API and the MCP server are on Creator, Pro, Studio and Podmaxxing. A plan buys access, throughput, monthly minutes and the AI tools; the free tier is the studio only.

Operations that spend credits on every call (starting a transcription, uploading a file, running an AI generator) carry their own budget, counted separately per key.

Read your budget from the headers

Every response carries them (on success, not only on a 429) so you can pace before you are refused.

RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 34
RateLimit-Policy: 120;w=60, 10000;w=86400

RateLimit-Limit and -Remaining are the current window; -Reset is seconds until it rolls over; -Policy lists every policy at once (120;w=60 is 120 per 60s). Retry-After appears on a 429 only, and honouring it beats your own backoff. Windows are fixed rather than sliding, so a burst spanning a boundary can briefly exceed the per-minute figure, the daily quota is what bounds total spend.

Two different 429s. rate_limited means slow down. too_many_in_flight means you are at the concurrency cap, backing off will not help unless one of *your own* jobs finishes. Always branch on error.code.

• Use webhooks instead of polling. On a busy account, polling is most of the daily budget.
• Pace on RateLimit-Remaining, not on catching 429s.
• Keep a window of concurrent jobs, not a burst: poll ?status=processing and start one as each finishes.
• One key per workload, so a runaway script exhausts its own budget and not your production key’s.

Credits

Transcription is paid for in credits: one credit is one minute of audio, rounded up, so a 52-minute episode costs 52. Exporting that transcript as SRT, then VTT, then JSON costs nothing further: you pay for the transcription, not per download. A YouTube caption track is free through this API: no speech engine runs. In the web app it is billed like any other source. Reading, listing, exporting and deleting are all free, and deleting does not refund.

{
  "plan": "pro",
  "credits_remaining_minutes": 412,
  "plan_allowance_minutes": 112,
  "purchased_minutes": 300,
  "transcriptions_total": 87,
  "scopes": ["transcriptions:read", "transcriptions:write"],
  "message": "About 6h 52m of transcription remaining."
}

Read-only and cheap, so an automated client can check before starting work rather than discovering mid-task that the account is empty. Working through a back catalogue, call it once and sum your episode durations, one check beats fifty 402s.

The balance is checked against the episode’s estimated duration before any work starts, so a long episode is refused up front with 402 insufficient_credits rather than half-transcribed. Nothing is charged for a refused request.

Plan allowance and purchased minutes

Your plan allowance resets monthly and is spendable anywhere. Purchased minutes, bought in packs, are spendable through the API and MCP only. An API call spends the allowance first and dips into purchased minutes for the remainder, so the perishable balance goes before the permanent one; GET /api/v1/usage reports both.

Purchased minutes do not expire on a date, but they are spendable only while your plan includes API access. Cancelling drops the account to the free tier, which cannot call the API, so a remaining purchased balance is paused rather than spendable. Nothing deletes it — the balance stays on the account and becomes spendable again as soon as you are back on a plan with API access.

When the plan is the problem

A 403 plan_required says the plan is wrong; a 402 insufficient_credits says the balance is empty. Retrying fixes neither, but only one needs a plan change. Plan is resolved per request, so an upgrade applies to the next call and rate limits move tier on the next window, scopes belong to the key, and a refused key starts succeeding the moment the plan grants it, with no change on your side. When a paid plan ends, write calls begin returning 403 plan_required; existing transcripts stay readable and exportable.