Get Usage
Retrieve credit balances, per-service activity counts, storage, and channels indexed for the authenticated user. All API operations consume credits from a shared pool — there are no per-service limits.
Retrieve your credit balances, resource usage counters, storage usage, and channel indexing metrics.
Overview
All API operations consume credits from a shared credit pool — there are no per-service limits. This endpoint gives you a complete picture of your account's consumption and remaining capacity.
What's Included
- Credits: Monthly allocation, remaining balance, and purchased credits
- Usage counters: Activity counts per resource type (informational, not individual limits)
- Storage: Used vs. allocated storage
- Channels indexed: Non-public YouTube channels indexed
- Subscription details: Plan, billing period, and status
Example Request
curl "https://api.vidnavigator.com/v1/usage" \
-H "X-API-Key: YOUR_API_KEY"Success Response (200 OK)
{
"status": "success",
"data": {
"usage_period": {
"start": "2026-03-01T00:00:00Z",
"end": "2026-04-01T00:00:00Z"
},
"billing_period": {
"start": "2026-03-15T00:00:00Z",
"end": "2026-04-15T00:00:00Z",
"interval": "month"
},
"subscription": {
"plan_id": "pro",
"plan_name": "Voyager",
"interval": "month",
"status": "active",
"cancel_at_period_end": false
},
"credits": {
"monthly_total": 100,
"monthly_remaining": 82.5,
"purchased": 50
},
"usage": {
"standard_request": { "used": 150 },
"residential_request": { "used": 45 },
"search_request": { "used": 30 },
"analysis_request": { "used": 12 },
"scene_analysis_hour": { "used": 3, "unit": "hours" },
"transcription_hour": { "used": 2.5, "unit": "hours" }
},
"channels_indexed": {
"used": 5,
"limit": 15,
"remaining": 10,
"percentage": 33.3
},
"storage": {
"used_bytes": 2684354560,
"used_formatted": "2.5 GB",
"limit_bytes": 536870912000,
"limit_formatted": "500 GB",
"remaining_bytes": 534186557440,
"remaining_formatted": "497.5 GB",
"percentage": 0.5
},
"generated_at": "2026-03-28T10:00:00Z"
}
}Credits Object
| Field | Type | Description |
|---|---|---|
monthly_total | number | "unlimited" | Total monthly credits included in your plan |
monthly_remaining | number | "unlimited" | Monthly credits remaining for the current period |
purchased | number | Additional purchased credits (persist across billing periods) |
Enterprise plans return "unlimited" for monthly_total and monthly_remaining. The shared credit pool is what limits usage — individual service counters under usage are informational only and do not impose per-service caps.
Usage Counters
The usage object shows how many resource units were used during the current period. These are activity counters — the shared credit pool is what actually limits usage.
| Counter | Description |
|---|---|
standard_request | Non-YouTube transcripts and non-proxy scraper page fetches |
residential_request | YouTube transcript retrievals and scraping requests that require residential proxies |
search_request | Semantic (vector) searches over already indexed content, including indexed YouTube channels and uploaded files (/search/file). Global YouTube and TikTok searches do not use this meter — they bill residential_request (and analysis_request for YouTube search). |
analysis_request | Video/file analysis and AI extraction units |
scene_analysis_hour | Scene analysis hours processed |
transcription_hour | Video/audio transcription hours processed by speech-to-text |
Channels Indexed
A hard plan limit (not credit-gated). Shows how many non-public YouTube channels you have indexed vs. your plan's capacity.
This endpoint reports cumulative usage for the billing period. To see what a single API call charged, pass include_usage=true on that call and read the returned usage block — see Per-Call Usage Disclosure.
Error: No Subscription
If you don't have an active subscription, the endpoint returns 404:
{
"status": "error",
"error": "no_subscription",
"message": "You are not subscribed to any plan."
}API reference
ApiKeyAuthX-API-Key<token>API key authentication. Include your VidNavigator API key in the X-API-Key header.
Usage statistics retrieved successfully
application/json- response
status?"success""success"data?Usage statistics for the authenticated user. All API operations consume credits from a shared pool — there are no per-service limits.
curl -X GET 'https://api.vidnavigator.com/v1/usage'{ "status": "success", "data": { "usage_period": { "start": "2019-08-24T14:15:22Z", "end": "2019-08-24T14:15:22Z" }, "billing_period": { "start": "2019-08-24T14:15:22Z", "end": "2019-08-24T14:15:22Z", "interval": "month" }, "subscription": { "plan_id": "string", "plan_name": "string", "interval": "month", "status": "string", "cancel_at_period_end": true }, "credits": { "monthly_total": 0, "monthly_remaining": 0, "purchased": 0 }, "usage": { "standard_request": { "used": 0, "unit": "string" }, "residential_request": { "used": 0, "unit": "string" }, "search_request": { "used": 0, "unit": "string" }, "analysis_request": { "used": 0, "unit": "string" }, "scene_analysis_hour": { "used": 0, "unit": "string" }, "transcription_hour": { "used": 0, "unit": "string" }, "frame_analysis": { "used": 0, "unit": "string" } }, "channels_indexed": { "used": 0, "limit": 0, "remaining": 0, "percentage": 0 }, "storage": { "used_bytes": 0, "used_formatted": "string", "limit_bytes": 0, "limit_formatted": "string", "remaining_bytes": 0, "remaining_formatted": "string", "percentage": 0 }, "generated_at": "2019-08-24T14:15:22Z" }}