> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```bash cURL theme={null}
curl "https://api.vidnavigator.com/v1/usage" \
-H "X-API-Key: YOUR_API_KEY"
```
```python Python theme={null}
import requests
url = "https://api.vidnavigator.com/v1/usage"
headers = {"X-API-Key": "YOUR_API_KEY"}
response = requests.get(url, headers=headers)
usage = response.json()
credits = usage["data"]["credits"]
print(f"Monthly remaining: {credits['monthly_remaining']}")
print(f"Purchased credits: {credits['purchased']}")
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.vidnavigator.com/v1/usage', {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const usage = await response.json();
const { credits } = usage.data;
console.log(`Monthly remaining: ${credits.monthly_remaining}`);
console.log(`Purchased credits: ${credits.purchased}`);
```
## Success Response (200 OK)
```json theme={null}
{
"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": 80,
"monthly_remaining": 62.5,
"purchased": 50
},
"usage": {
"standard_request": { "used": 150 },
"residential_request": { "used": 45 },
"search_request": { "used": 30 },
"analysis_request": { "used": 12 },
"video_scene_analyses": { "used": 3 },
"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` | Video searches across YouTube or your own files |
| `analysis_request` | Video/file analysis and AI extraction units |
| `video_scene_analyses` | Scene analysis requests |
| `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.
### Error: No Subscription
If you don't have an active subscription, the endpoint returns `404`:
```json theme={null}
{
"status": "error",
"error": "no_subscription",
"message": "You are not subscribed to any plan."
}
```
## OpenAPI
````yaml GET /usage
openapi: 3.0.3
info:
title: VidNavigator Developer API
description: >-
The VidNavigator Developer API provides programmatic access to video
analysis, transcription, and search capabilities.
## Authentication
All endpoints require API key authentication via the `X-API-Key` header:
```
X-API-Key: YOUR_API_KEY
```
## Rate Limits
Check the documentation for the rate limits for each endpoint.
## Error Handling
The API uses standard HTTP status codes and returns error responses in JSON
format:
```json
{
"status": "error",
"error": "error_type",
"message": "Human readable error message"
}
```
version: 1.0.0
contact:
name: VidNavigator Support
url: https://vidnavigator.com/support
email: support@vidnavigator.com
license:
name: Proprietary
url: https://vidnavigator.com/terms
servers:
- url: https://api.vidnavigator.com/v1
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Transcripts
description: Extract transcripts from online videos
- name: TikTok
description: Scrape TikTok profile metadata and per-video stats
- name: Files
description: Manage uploaded audio/video files
- name: Analysis
description: AI-powered content analysis
- name: Extraction
description: >-
Extract structured data from video and file transcripts using custom
schemas
- name: Namespaces
description: Organize uploaded files into namespaces (folders)
- name: Search
description: Search videos and files using AI
- name: System
description: System health and information
- name: Tweet Analysis
description: Extract structured claims and metadata from X/Twitter tweets
paths:
/usage:
get:
tags:
- System
summary: Get usage statistics
description: >-
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.
operationId: getUsage
responses:
'200':
description: Usage statistics retrieved successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
data:
$ref: '#/components/schemas/UsageData'
'403':
$ref: '#/components/responses/AccessDenied'
'404':
description: No active subscription found
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
message:
type: string
example:
status: error
error: no_subscription
message: You are not subscribed to any plan.
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
UsageData:
type: object
description: >-
Usage statistics for the authenticated user. All API operations consume
credits from a shared pool — there are no per-service limits.
properties:
usage_period:
type: object
description: Monthly usage window (credits reset each period)
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
billing_period:
type: object
description: Actual subscription billing window (Stripe period)
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
interval:
type: string
enum:
- month
- year
subscription:
type: object
properties:
plan_id:
type: string
plan_name:
type: string
interval:
type: string
enum:
- month
- year
status:
type: string
cancel_at_period_end:
type: boolean
credits:
$ref: '#/components/schemas/CreditsInfo'
usage:
type: object
description: >-
Activity counters for each service type during the current period.
These are informational — the shared credit pool is what limits
usage, not per-service caps.
properties:
video_transcripts:
$ref: '#/components/schemas/ActivityCount'
youtube_transcripts:
$ref: '#/components/schemas/ActivityCount'
video_searches:
$ref: '#/components/schemas/ActivityCount'
video_analyses:
$ref: '#/components/schemas/ActivityCount'
video_scene_analyses:
$ref: '#/components/schemas/ActivityCount'
video_uploads:
allOf:
- $ref: '#/components/schemas/ActivityCount'
description: Upload usage in hours
channels_indexed:
$ref: '#/components/schemas/CapacityMetric'
description: >-
Number of non-public YouTube channels indexed by this user. Hard
plan limit — not credit-gated.
storage:
$ref: '#/components/schemas/StorageUsage'
generated_at:
type: string
format: date-time
CreditsInfo:
type: object
description: >-
Shared credit pool that gates all API operations. Monthly credits reset
each billing period; purchased credits persist.
properties:
monthly_total:
oneOf:
- type: number
- type: string
enum:
- unlimited
description: Total monthly credits included in the plan
monthly_remaining:
oneOf:
- type: number
- type: string
enum:
- unlimited
description: Monthly credits remaining for the current period
purchased:
type: number
description: Additional purchased credits (persist across periods)
required:
- monthly_total
- monthly_remaining
- purchased
ActivityCount:
type: object
description: >-
Activity counter for a credit-gated service. No per-service limit —
usage is gated by the shared credit pool.
properties:
used:
type: number
description: Number of times this service was used during the current period
unit:
type: string
description: >-
Unit of measurement when not a simple count (e.g., 'hours' for video
uploads). Omitted for count-based metrics.
required:
- used
CapacityMetric:
type: object
description: A capacity metric with a hard plan limit (not credit-gated).
properties:
used:
type: integer
description: Current count
limit:
oneOf:
- type: integer
- type: string
enum:
- unlimited
description: Plan limit
remaining:
oneOf:
- type: integer
- type: string
enum:
- unlimited
description: Remaining capacity
percentage:
type: number
description: Usage percentage (0-100)
required:
- used
- limit
- remaining
- percentage
StorageUsage:
type: object
properties:
used_bytes:
type: integer
used_formatted:
type: string
limit_bytes:
oneOf:
- type: integer
- type: string
enum:
- unlimited
limit_formatted:
type: string
remaining_bytes:
oneOf:
- type: integer
- type: string
enum:
- unlimited
remaining_formatted:
type: string
percentage:
type: number
responses:
AccessDenied:
description: Access denied - insufficient permissions
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
enum:
- access_denied
message:
type: string
InternalServerError:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
enum:
- internal_server_error
message:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
API key authentication. Include your VidNavigator API key in the
X-API-Key header.
````