Usage Costs
Understand how API operations consume credits from your shared credit pool.
Overview
Your VidNavigator plan includes a monthly credit pool shared across all API operations. Different services consume credits at different rates. You can monitor your current balance at any time by calling the /usage endpoint.
There are no per-service limits — all operations draw from the same credit pool. The activity counters shown in /usage are informational only.
Credit Costs per Service
| Resource Unit | Credit Conversion | Used By |
|---|---|---|
Standard Requests (standard_request) | 1 credit = 10,000 non-YouTube transcripts or non-proxy scraper pages | /transcript (non-YouTube), non-proxy TikTok profile pages |
Residential Proxy Requests (residential_request) | 1 credit = 200 residential fetches | /transcript (YouTube), /youtube/search, /tiktok/search (per 30 videos returned), /tiktok/live/search (per 30 rooms returned), /tiktok/live/room (1 per room, 2 with comments), proxy-backed TikTok profile pages |
Analysis Requests (analysis_request) | 1 credit = 100 analysis requests (token-based, see below) | /analyze/video, /analyze/file, /extract/video, /extract/file, /youtube/search, /search/file, /tweet/statement |
Search Requests (search_request) | 1 credit = 1,000 semantic searches | Indexed YouTube channel search, /search/file |
Transcription Hours (transcription_hour) | 1 credit = 3 hours of video/audio transcription | /upload/file, /transcribe (and /transcribe/async), speech-to-text fallback |
Frames Watched (frame_analysis) | 1 credit = 2,000 video frames analyzed (at least 667 per hour of video) | /watch (and /watch/async); include_scenes on /analyze/video, /extract/video and their async routes; the scenes of an uploaded file (/upload/file with include_scenes, /file/{file_id}/scenes) |
Scene Analysis Hours (scene_analysis_hour) | 1 credit = 1 hour of scene analysis | Scene analysis endpoints |
Deduction Order
Credits are deducted in this order:
- Monthly credits are consumed first
- Purchased credits cover any overflow
Monthly credits reset each billing period. Purchased credits persist across periods.
Plan Credit Allowances
| Plan | Monthly Credits | Storage | Indexed Channels |
|---|---|---|---|
| Trial | 5 | 5 GB | 2 |
| Navigator ($19.99/mo) | 20 | 50 GB | 3 |
| Voyager ($79.99/mo) | 100 | 500 GB | 15 |
| Odyssey (Custom) | Unlimited | Unlimited | Unlimited |
Voyager and above can purchase additional credit packs: 50 credits ($20), 300 credits ($100), or 1,200 credits ($300).
Service Details
Standard Requests
Each non-YouTube transcript request to /transcript consumes standard_request units. 1 credit covers 10,000 standard requests.
Residential Proxy Requests
Fetches that route through residential proxies consume residential_request units. 1 credit covers 200 residential requests.
metadata_only: true routes through the residential proxy and is billed as a residential_request. YouTube search bills per residential page fetched; TikTok keyword search bills 1 residential_request per 30 videos it returns, and TikTok LIVE search 1 per 30 rooms it returns (minimum 1 per search, and 1 per 5 TikTok pages read). A TikTok LIVE room bills 1, or 2 with include_comments (1 when the room has ended); a room that does not exist is not billed.Transcription Hours
/transcribe, /upload/file, and speech-to-text fallback consume transcription_hour units. 1 credit covers 3 hours of audio/video processed.
/upload/file also count towards your storage quota.Frames Watched
/watch consumes one frame_analysis unit per frame of the video it analyzes. 1 credit covers 2,000 frames. The number of frames follows the picture and the detail level, with at least 667 per hour of video, so an hour of video watched never costs less than an hour of transcription.
The same unit pays for the scenes asked with include_scenes on /analyze/video and /extract/video: the frames are charged on top of the analysis, at each call. For an uploaded file they are charged once, when its scenes are analyzed; using them afterwards in /analyze/file or /extract/file adds no frame charge.
/watch also bills the fetch of the video (standard_request or residential_request) and, when the video has no captions, transcription_hour for the speech-to-text. See Watch billing.Analysis Requests
/analyze/*, /extract/*, /youtube/search, /search/file, and /tweet/statement consume analysis_request units. 1 credit covers 100 analysis requests.
analysis_request unit covers up to 15,000 total tokens. Larger contexts use ceil(total_tokens / 15000) units. Multiple internal LLM calls in one request are consolidated into a single charge.Search Requests
Semantic (vector) searches over already indexed content consume a search_request unit. This includes indexed YouTube channel search and each call to /search/file. 1 credit covers 1,000 semantic searches.
/youtube/search) TikTok keyword search (/tiktok/search) and TikTok LIVE search (/tiktok/live/search) do not bill search_request — they bill per residential_request (and analysis_request for YouTube search) instead.Data Extraction
Each call to /extract/video or /extract/file uses AI to extract structured data from transcripts. Analysis Request units scale with token usage.
Per-Call Usage Disclosure
Most billable endpoints accept an include_usage flag. When set to true, the response includes a usage block that lists exactly what was charged for that specific call — every meter that fired, the net credits deducted, and (for LLM endpoints) the token tally.
{
"usage": {
"charges": [
{ "service_type": "residential_request", "quantity": 5, "credits": 0.025 },
{
"service_type": "analysis_request",
"quantity": 2,
"credits": 0.02,
"tokens": { "prompt_tokens": 24000, "completion_tokens": 4200, "total_tokens": 28200 }
}
],
"total_credits": 0.045
}
}| Field | Description |
|---|---|
charges[] | One entry per meter (service_type). Multiple billings of the same meter in one request are consolidated. |
charges[].quantity | Net units consumed. For analysis_request this is ceil(total_tokens / 15000); for transcription_hour / scene_analysis_hour it's in hours; for frame_analysis it's the number of frames. |
charges[].credits | Net credits deducted for this meter (0 when waived). |
charges[].waived / credits_saved | Present when a charge was waived via a cache-hit sponsorship. |
charges[].tokens | Only on the analysis_request entry for LLM endpoints — cumulative prompt_tokens / completion_tokens / total_tokens. |
total_credits | Net credits deducted by the whole request. |
For async endpoints (/transcribe/async, /extract/video/async, /tweet/statement/async, /tiktok/profile, /tiktok/search, /tiktok/live/search), billing happens in the background worker, so include_usage is passed on the polling GET (once task_status=completed), not on submit. See Async Jobs.
Async Jobs and Long Videos
- Async endpoints are billed exactly like their synchronous counterparts — the async mode costs nothing extra.
- Polling result endpoints is free.
- A failed async job has all of its charges reverted.
- Async submit endpoints return
402 limit_exceededwhen less than 60 seconds of transcription credit is left. The real, duration-based charge is computed when the job runs. - A synchronous request rejected with
video_too_long(media longer than 10 minutes) still bills the metadata fetch that read the duration (standard_requestorresidential_request, not refunded). Notranscription_houris charged, since no audio is processed.
This per-call usage block is distinct from the aggregate GET /usage endpoint, which reports cumulative counters and balances for the whole billing period.
Hard Limits (Not Credit-Gated)
Some resources have fixed plan limits that are not deducted from your credit pool:
| Resource | How It's Enforced |
|---|---|
| Storage | Total file storage in bytes checked against your plan's storage cap |
| Indexed Channels | Non-public YouTube channels counted live from your channel list against your plan's cap |
YouTube vs Other Platforms
Why do Residential Proxy Requests cost more?
YouTube and some scraper flows require residential proxy infrastructure for reliable access. This is reflected in the credit rate (1 credit per 200 Residential Proxy Requests vs. 1 per 10,000 Standard Requests).
Free Endpoints
The following endpoints do not consume credits:
GET /files— List your uploaded filesGET /file/{file_id}— Get file info and transcriptGET /file/{file_id}/url— Get temporary file URLGET /namespaces— List namespacesPOST /namespaces— Create a namespacePUT /namespaces/{namespace_id}— Rename a namespaceDELETE /namespaces/{namespace_id}— Delete a namespacePUT /file/{file_id}/namespaces— Update file namespace assignmentsGET /tiktok/profile/{task_id}— Poll a TikTok profile scrape (billing happens in the background worker)GET /tiktok/search/{task_id}— Poll a TikTok keyword search (billing happens in the background worker)GET /tiktok/live/search/{task_id}— Poll a TikTok LIVE search (billing happens in the background worker)GET /health— Health checkGET /usage— Usage statistics