Usage Costs

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`, 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`, speech-to-text fallback
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.

For YouTube, even metadata_only: true routes through the residential proxy and is billed as a residential_request. YouTube search and TikTok search also bill per residential page fetched.

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.

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) and TikTok keyword search (/tiktok/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.
`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 the async TikTok endpoints, billing happens in the background worker, so include_usage is passed on the polling GET (once task_status=completed), not on submit. See TikTok Search Result and TikTok Profile Result.

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 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 /health — Health check
GET /usage — Usage statistics

API Documentation

Online media

Local Files

System

Overview

Credit Costs per Service

Deduction Order

Plan Credit Allowances

Service Details

Standard Requests

Residential Proxy Requests

Transcription Hours

Analysis Requests

Search Requests

Data Extraction

Per-Call Usage Disclosure

Hard Limits (Not Credit-Gated)

YouTube vs Other Platforms

Free Endpoints

​Overview

​Credit Costs per Service

​Deduction Order

​Plan Credit Allowances

​Service Details

Standard Requests

Residential Proxy Requests

Transcription Hours

Analysis Requests

Search Requests

Data Extraction

​Per-Call Usage Disclosure

​Hard Limits (Not Credit-Gated)

​YouTube vs Other Platforms

​Free Endpoints

Overview

Credit Costs per Service

Deduction Order

Plan Credit Allowances

Service Details

Per-Call Usage Disclosure

Hard Limits (Not Credit-Gated)

YouTube vs Other Platforms

Free Endpoints