> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tornadoapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Usage

> Get your API usage statistics

## Overview

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

## Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

## Response

<ResponseField name="client_name" type="string">
  Your account/client name
</ResponseField>

<ResponseField name="usage_count" type="integer">
  Total number of jobs created
</ResponseField>

<ResponseField name="storage_usage_gb" type="number">
  Total storage used in gigabytes
</ResponseField>

<ResponseField name="storage_reserved_gb" type="number">
  Storage currently reserved by in-progress jobs (in gigabytes). Released when jobs complete or fail.
</ResponseField>

<ResponseField name="storage_effective_usage_gb" type="number">
  Effective storage usage: `storage_usage_gb + storage_reserved_gb`. Used for quota enforcement.
</ResponseField>

<ResponseField name="billing_period_start" type="string">
  Start of current billing period (if Stripe billing enabled)
</ResponseField>

<ResponseField name="billing_period_end" type="string">
  End of current billing period (if Stripe billing enabled)
</ResponseField>

<ResponseField name="current_period_usage_gb" type="number">
  Storage used in current billing period (if Stripe billing enabled)
</ResponseField>

<ResponseField name="storage_limit_gb" type="number">
  Storage limit in gigabytes (only present for trial/limited keys)
</ResponseField>

<ResponseField name="storage_limit_bytes" type="integer">
  Storage limit in bytes (only present for trial/limited keys)
</ResponseField>

<ResponseField name="storage_remaining_gb" type="number">
  Remaining storage in gigabytes before quota is reached (only present for trial/limited keys)
</ResponseField>

<ResponseField name="billing_error" type="string">
  Error message when billing info retrieval fails (only present when Stripe billing is configured and an error occurs)
</ResponseField>

<ResponseField name="max_resolution_limit" type="string">
  Maximum video resolution allowed for this API key (e.g., `"720"`, `"1080"`). Only present if a resolution limit is configured.
</ResponseField>

<ResponseField name="max_duration_limit_seconds" type="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.
</ResponseField>

<ResponseField name="max_filesize_limit_bytes" type="integer">
  Maximum file size per video in bytes. Only present if a file size limit is configured.
</ResponseField>

<ResponseField name="max_filesize_limit_mb" type="number">
  Maximum file size per video in megabytes. Only present if a file size limit is configured.
</ResponseField>

## Example

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.tornadoapi.io/usage" \
    -H "x-api-key: sk_your_api_key"
  ```

  ```json Response theme={null}
  {
    "client_name": "My Application",
    "usage_count": 1523,
    "storage_usage_gb": 45.67,
    "storage_reserved_gb": 0.52,
    "storage_effective_usage_gb": 46.19
  }
  ```

  ```json Response (With Billing) theme={null}
  {
    "client_name": "My Application",
    "usage_count": 1523,
    "storage_usage_gb": 45.67,
    "storage_reserved_gb": 0.52,
    "storage_effective_usage_gb": 46.19,
    "billing_period_start": "2024-01-01T00:00:00Z",
    "billing_period_end": "2024-02-01T00:00:00Z",
    "current_period_usage_gb": 12.34
  }
  ```

  ```json Response (Trial Key with Storage Limit) theme={null}
  {
    "client_name": "My Trial Account",
    "usage_count": 42,
    "storage_usage_gb": 3.0,
    "storage_reserved_gb": 0.0,
    "storage_effective_usage_gb": 3.0,
    "storage_limit_gb": 1024.0,
    "storage_limit_bytes": 1099511627776,
    "storage_remaining_gb": 1021.0
  }
  ```

  ```json Response (Key with Limits) theme={null}
  {
    "client_name": "Limited Key",
    "usage_count": 100,
    "storage_usage_gb": 5.0,
    "storage_reserved_gb": 0.0,
    "storage_effective_usage_gb": 5.0,
    "max_resolution_limit": "1080",
    "max_duration_limit_seconds": 600,
    "max_filesize_limit_bytes": 524288000,
    "max_filesize_limit_mb": 500.0
  }
  ```
</CodeGroup>

## Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "client_name": "My Application",
    "usage_count": 1523,
    "storage_usage_gb": 45.67,
    "storage_reserved_gb": 0.52,
    "storage_effective_usage_gb": 46.19
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Missing x-api-key header"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API Key"
  }
  ```
</ResponseExample>

## 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)

<Note>
  Deleting files from S3 does not decrease the storage counter. This metric tracks total data transferred.
</Note>

### 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:

```json theme={null}
{
  "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:

| Field                        | Stripe Key | Trial Key | No 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_error`              |  on error  |     —     |     —    |
| `storage_limit_gb`           |      —     |     ✓     |     —    |
| `storage_limit_bytes`        |      —     |     ✓     |     —    |
| `storage_remaining_gb`       |      —     |     ✓     |     —    |
| `max_resolution_limit`       |   if set   |   if set  |  if set  |
| `max_duration_limit_seconds` |   if set   |   if set  |  if set  |
| `max_filesize_limit_bytes`   |   if set   |   if set  |  if set  |
| `max_filesize_limit_mb`      |   if set   |   if set  |  if set  |

## Monitoring Usage

```python theme={null}
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")
```