Quotas & credits
API consumption shares the same monthly quota as the web UI. There is no separate “API quota”. Your plan grants a fixed number of credits per billing cycle, shared by the web app, public API, and MCP. One transcript costs 1 credit. One nonempty comments page costs 1 credit; search and video details remain free.
Plans
| Plan | Price | Credits / cycle | API access |
|---|---|---|---|
| Free | $0 | 30 | All sync endpoints and saved-job reads; no API/MCP bulk creation |
| Starter | $9 | 1,000 | Full (sync + bulk) |
| Pro | $19 | 5,000 | Full (sync + bulk) |
| Business | $49 | 20,000 | Full (sync + bulk) |
Free credits renew every 30 days from signup; paid credits renew on the subscription's billing cycle. Unused credits do not roll over. Website transcript and comments collections are available on Free within the balance. Compare plans on the pricing page.
When credits are deducted
| Action | Charge | Refund? |
|---|---|---|
GET /transcript/:id | 1 credit, charged after the transcript fetch and any format conversion succeed (charge-on-success) | No refund path needed. Failed fetches and failed formats never reach the charge step |
GET /comments/:id | 1 credit per nonempty page, including replies | Errors and empty pages are not charged |
POST /jobs | N credits upfront, or 2N with include_comments, where N is the number of videos resolved | Failed transcripts and unused comment reservations are refunded when the job finishes |
DELETE /jobs/:id | Free | Refunds unused reservations: undelivered transcripts and unused comments, or unspent pages for a standalone comments collection |
| Search, video info, channel/playlist listings, usage, and saved-job reads/exports | Free | n/a |
Standalone website comments collections reserve the credit limit you choose for the whole job, not one credit per video. Each nonempty page uses 1 credit from that reservation. Empty pages and failed requests cost nothing; unused reservation is refunded when collection ends or is canceled. Replies share the budget.
Sync transcripts: charge-on-success
GET /transcript/:id uses a charge-on-success flow:
- Check that at least 1 credit is available
- Fetch the transcript
- Format if a non-JSON format was requested
- Charge 1 credit
- Send the response
A failure at any step before the charge, such as a fetch error or formatter error, never reaches the charge step, so you're not billed and there's no refund window. If another request consumes the remaining quota before the charge, this request returns 402.
Comments: one credit per nonempty page
Bulk jobs can opt into one Top page per successful transcript. They reserve 2 credits per video up front and refund failed transcripts and unused comments at completion or cancellation. Downloads and reads of those saved comments do not spend another credit.
GET /api/v1/comments/:videoId and the MCP tool get_video_comments require at least 1 available credit before fetching. Each nonempty page costs 1 credit, whether it is Top, Newest, a continuation, or a reply thread. A page usually holds about 20 top-level comments; YouTube controls the size and reply pages can be smaller. This is a per-page charge, not per comment. Errors and empty pages are not charged.
MCP get_transcript with include_comments: true costs 2 credits when both the transcript and comments page succeed. If comments fail, return an empty page, or there is only enough credit for the transcript, only the transcript credit is spent. A comments error does not discard a successful transcript. Website comments use the same rule: fetching is optional and each nonempty page costs 1 credit.
For example, 10 transcripts and 5 nonempty comments pages use 15 credits from the same balance. The Free plan gives 30 credits every 30 days from signup; paid plans refill on their billing cycle.
Bulk job accounting walkthrough
Example: submit a channel with 500 videos on a Pro plan.
- POST resolves the channel to 500 videos. -500 credits.
- 480 videos succeed, 15 fail with video unavailable, 5 fail with no captions. +20 credits refunded when the job finishes.
- Net spend: 480 credits.
If you cancel after 100 successful transcripts with no other finished items, the remaining 400 credits are refunded. With comments enabled, the unused comments reservation is refunded too.
Refunds belong to the cycle that paid for the job. If that cycle has already ended, its unused reservation is recorded as refunded but does not increase the new cycle's balance.
Quota errors
If you don't have enough credits to fulfill a request, the API returns 402 insufficient_quota with the remaining and needed counts in the message.
Check your current state at any time with GET /api/v1/usage. The endpoint is free, doesn't consume quota, and is safe to poll before submitting bulk work.