Skip to main content
GET
/
usage
Get Usage
curl --request GET \
  --url https://api.tornadoapi.io/usage \
  --header 'x-api-key: <x-api-key>'
{
  "client_name": "My Application",
  "usage_count": 1523,
  "storage_usage_gb": 45.67,
  "storage_reserved_gb": 0.52,
  "storage_effective_usage_gb": 46.19
}

​
Overview

Returns usage statistics for your API key, including job count and storage usage.

​
Header Parameters

​
x-api-key
string
required
Your API key for authentication

​
Response

​
client_name
string
Your account/client name
​
usage_count
integer
Total number of jobs created
​
storage_usage_gb
number
Total storage used in gigabytes
​
storage_reserved_gb
number
Storage currently reserved by in-progress jobs (in gigabytes). Released when jobs complete or fail.
​
storage_effective_usage_gb
number
Effective storage usage: storage_usage_gb + storage_reserved_gb. Used for quota enforcement.
​
billing_period_start
string
Start of current billing period (if Stripe billing enabled)
​
billing_period_end
string
End of current billing period (if Stripe billing enabled)
​
current_period_usage_gb
number
Storage used in current billing period (if Stripe billing enabled)
​
storage_limit_gb
number
Storage limit in gigabytes (only present for trial/limited keys)
​
storage_limit_bytes
integer
Storage limit in bytes (only present for trial/limited keys)
​
storage_remaining_gb
number
Remaining storage in gigabytes before quota is reached (only present for trial/limited keys)
​
billing_error
string
Error message when billing info retrieval fails (only present when Stripe billing is configured and an error occurs)
​
max_resolution_limit
string
Maximum video resolution allowed for this API key (e.g., "720", "1080"). Only present if a resolution limit is configured.
​
max_duration_limit_seconds
integer
Maximum video duration in seconds allowed for this API key (e.g., 600 for 10 min). Only present if a duration limit is configured.
​
max_filesize_limit_bytes
integer
Maximum file size per video in bytes. Only present if a file size limit is configured.
​
max_filesize_limit_mb
number
Maximum file size per video in megabytes. Only present if a file size limit is configured.

​
Example

curl -X GET "https://api.tornadoapi.io/usage" \
  -H "x-api-key: sk_your_api_key"

​
Success Response

{
  "client_name": "My Application",
  "usage_count": 1523,
  "storage_usage_gb": 45.67,
  "storage_reserved_gb": 0.52,
  "storage_effective_usage_gb": 46.19
}

​
Error Responses

{
  "error": "Missing x-api-key header"
}

​
Usage Tracking

​
Job Count

Incremented each time you call POST /jobs. For batch operations, each episode counts as one job.

​
Storage Usage

Cumulative total of all files uploaded to S3. This includes:
  • Successfully completed videos
  • All formats (MP4, MKV, MP3)
Deleting files from S3 does not decrease the storage counter. This metric tracks total data transferred.

​
Storage Quota (Trial Keys)

API keys with a storage limit (e.g., 1 TB trial keys) include quota information in the response. When the limit is reached, new jobs are rejected with a 403 Forbidden error: 
{
  "error": "Storage quota exceeded",
  "limit_gb": "1024.00",
  "used_gb": "1024.00",
  "message": "This API key has a 1024 GB limit and has used 1024.00 GB"
}
The response fields vary depending on your key type:
FieldStripe KeyTrial KeyNo Limit
client_name✓✓✓
usage_count✓✓✓
storage_usage_gb✓✓✓
storage_reserved_gb✓✓✓
storage_effective_usage_gb✓✓✓
billing_period_start✓——
billing_period_end✓——
current_period_usage_gb✓——
billing_erroron error——
storage_limit_gb—✓—
storage_limit_bytes—✓—
storage_remaining_gb—✓—
max_resolution_limitif setif setif set
max_duration_limit_secondsif setif setif set
max_filesize_limit_bytesif setif setif set
max_filesize_limit_mbif setif setif set

​
Monitoring Usage

import requests

def check_usage(api_key):
    response = requests.get(
        "https://api.tornadoapi.io/usage",
        headers={"x-api-key": api_key}
    )
    data = response.json()

    print(f"Client: {data['client_name']}")
    print(f"Jobs: {data['usage_count']}")
    print(f"Storage: {data['storage_usage_gb']:.2f} GB")

    # Trial key with storage limit
    if "storage_limit_gb" in data:
        print(f"Limit: {data['storage_limit_gb']:.2f} GB")
        print(f"Remaining: {data['storage_remaining_gb']:.2f} GB")

    # Stripe billing key
    if "current_period_usage_gb" in data:
        print(f"Current period: {data['current_period_usage_gb']:.2f} GB")

check_usage("sk_your_api_key")