Skip to Content

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 UnitCredit ConversionUsed 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 searchesIndexed 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 analysisScene analysis endpoints

Deduction Order

Credits are deducted in this order:

  1. Monthly credits are consumed first
  2. Purchased credits cover any overflow

Monthly credits reset each billing period. Purchased credits persist across periods.

Plan Credit Allowances

PlanMonthly CreditsStorageIndexed Channels
Trial55 GB2
Navigator ($19.99/mo)2050 GB3
Voyager ($79.99/mo)100500 GB15
Odyssey (Custom)UnlimitedUnlimitedUnlimited

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.

For YouTube, even 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.

Files uploaded via /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.

LLM analysis is token-based: 1 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.

Global YouTube search (/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
  }
}
FieldDescription
charges[]One entry per meter (service_type). Multiple billings of the same meter in one request are consolidated.
charges[].quantityNet 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[].creditsNet credits deducted for this meter (0 when waived).
charges[].waived / credits_savedPresent when a charge was waived via a cache-hit sponsorship.
charges[].tokensOnly on the analysis_request entry for LLM endpoints — cumulative prompt_tokens / completion_tokens / total_tokens.
total_creditsNet 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_exceeded when 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_request or residential_request, not refunded). No transcription_hour is 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:

ResourceHow It's Enforced
StorageTotal file storage in bytes checked against your plan's storage cap
Indexed ChannelsNon-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 files
  • GET /file/{file_id} — Get file info and transcript
  • GET /file/{file_id}/url — Get temporary file URL
  • GET /namespaces — List namespaces
  • POST /namespaces — Create a namespace
  • PUT /namespaces/{namespace_id} — Rename a namespace
  • DELETE /namespaces/{namespace_id} — Delete a namespace
  • PUT /file/{file_id}/namespaces — Update file namespace assignments
  • GET /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 check
  • GET /usage — Usage statistics

On this page