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

# Storage & Operations

> Understanding how Imperial tracks storage and operations for fair, predictable billing

## How Imperial Billing Works

Imperial uses a transparent, usage-based system with two key metrics:

<CardGroup cols={2}>
  <Card title="Storage" icon="hard-drive">
    Total bytes stored in your account
  </Card>

  <Card title="Operations" icon="chart-line">
    Weighted count of API actions
  </Card>
</CardGroup>

## Storage

Storage is measured in bytes and counts toward your tier's limit.

### What Counts as Storage?

✅ **Counted:**

* Uploaded images (compressed or original)
* Uploaded videos
* Video thumbnails

❌ **Not Counted:**

* Deleted files (instant reclamation)
* Failed uploads
* Temporary processing files

### Storage Calculation

```javascript theme={null}
Storage Used = Sum of all file sizes in your account
```

**Example:**

* 100 images × 500 KB each = 50 MB
* 10 videos × 20 MB each = 200 MB
* **Total: 250 MB used**

<Info>Check your current storage usage in the [Dashboard Overview](https://app.imperial.gay).</Info>

### Reducing Storage Usage

<Tabs>
  <Tab title="Auto-Compression">
    Enable in [Settings → Uploads](https://app.imperial.gay/settings) - **High Quality (80):** \~40%
    smaller - **Balanced (65):** \~55% smaller - **Optimized (50):** \~70% smaller Compression is
    applied before upload, so you only pay for the compressed size.
  </Tab>

  <Tab title="Delete Old Files">
    Delete unused files to instantly reclaim storage: `bash curl -X DELETE
          https://api.imperial.gay/images/{id} \ -H "Authorization: Bearer YOUR_API_KEY" ` Or use bulk
    delete in the dashboard.
  </Tab>

  <Tab title="Video Optimization">
    Videos aren't compressed (to preserve quality), but you can: - Upload in efficient formats (MP4
    with H.264) - Pre-compress videos before upload - Use lower resolutions for non-critical content
  </Tab>
</Tabs>

## Operations

Operations measure your API activity with a weighted system that makes reads much cheaper than writes.

### Operation Classes

<AccordionGroup>
  <Accordion title="Class A Operations (Weight: 1.0)" icon="arrow-up">
    **Heavy operations** that modify or create resources. **Counted Actions:** - `POST
            /images/upload` - Upload file - `DELETE /images/:id` - Delete file **Operation Count:** - Each
    action = **1.0 operation** - 10,000 uploads = 10,000 operations

    <Warning>
      Class A operations consume your limit faster. Optimize your upload workflows to stay within
      limits.
    </Warning>
  </Accordion>

  <Accordion title="Class B Operations (Weight: 0.1)" icon="arrow-down">
    **Light operations** that only read data. **Counted Actions:** - File views via CDN URLs -
    Public image/video access **Operation Count:** - Each action = **0.1 operation** - 10,000 views
    \= 1,000 operations

    <Tip>
      Views are 10x cheaper! Your files can be viewed millions of times for a fraction of your
      operation limit.
    </Tip>
  </Accordion>
</AccordionGroup>

### Operation Tracking

Every action is logged with:

* Operation type (upload, delete, view)
* Class (A or B)
* Weight (1.0 or 0.1)
* Timestamp
* Resource ID
* API key used (Pro/Business only)

<Info>
  Pro and Business users can view detailed operation logs in the [API
  Dashboard](https://app.imperial.gay/api).
</Info>

### Real-World Examples

<Tabs>
  <Tab title="Content Creator">
    **Monthly Activity:** - Upload 500 screenshots (500 Class A ops) - Screenshots get 50,000 views
    (5,000 Class B ops) - Delete 100 old files (100 Class A ops) **Total: 5,600 operations** ✅ Fits
    in **Starter tier** (100K ops)
  </Tab>

  <Tab title="Small Website">
    **Monthly Activity:** - Upload 200 product images (200 Class A ops) - Images get 500,000 page
    views (50,000 Class B ops) - Update 50 images (50 Class A ops) **Total: 50,250 operations** ✅
    Fits in **Starter tier** (100K ops)
  </Tab>

  <Tab title="API Integration">
    **Monthly Activity:** - Upload 5,000 user avatars (5,000 Class A ops) - Avatars get 2M views
    (200,000 Class B ops) - Delete 1,000 old avatars (1,000 Class A ops) **Total: 206,000 operations**
    ⚠️ Need **Pro tier** (1M ops)
  </Tab>

  <Tab title="High-Traffic App">
    **Monthly Activity:** - Upload 50,000 images (50,000 Class A ops) - Images get 20M views (2M
    Class B ops) - Delete 10,000 images (10,000 Class A ops) **Total: 2,060,000 operations** ⚠️ Need
    **Business tier** (5M ops)
  </Tab>
</Tabs>

## Monitoring Your Usage

### Dashboard Overview

View your current usage at [app.imperial.gay](https://app.imperial.gay):

* **Storage:** Progress bar showing GB used / GB limit
* **Operations:** Monthly count with reset date
* **Charts:** 7/30/90-day breakdowns
* **Projections:** Estimated usage by month end

### API Response Headers

Every API response includes usage headers:

```http theme={null}
X-Operations-Used: 45678
X-Operations-Limit: 100000
X-Storage-Used: 2147483648
X-Storage-Limit: 5368709120
```

### Usage Alerts

Pro and Business users receive alerts at:

* 50% of operation limit
* 80% of operation limit
* 90% of operation limit
* 100% of operation limit

## Overages & Limits

### What Happens When You Hit Limits?

<Tabs>
  <Tab title="Storage Limit">
    **When you reach your storage limit:**

    ❌ New uploads will fail with error:

    ```json theme={null}
    {
      "error": "Storage limit exceeded. You've used 5.0 GB of 5 GB.",
      "statusCode": 413
    }
    ```

    ✅ Existing files remain accessible
    ✅ Views still work (don't consume storage)

    **Solutions:**

    * Enable auto-compression
    * Delete old uploads
    * Upgrade to higher tier
  </Tab>

  <Tab title="Operations Limit">
    **When you reach your operations limit:**

    ❌ API requests are rate-limited
    ❌ New uploads may be delayed

    ✅ Existing files remain accessible
    ✅ CDN delivery continues normally

    **Solutions:**

    * Wait for monthly reset
    * Optimize upload frequency
    * Upgrade to higher tier
  </Tab>
</Tabs>

### No Surprise Charges

<Check>
  Imperial never charges overages. You're limited to your tier's allocation, but you'll never
  receive unexpected bills.
</Check>

## Best Practices

### Optimize Storage

<Steps>
  <Step title="Enable Auto-Compression">
    Reduce image sizes by 40-70% with negligible quality loss
  </Step>

  <Step title="Clean Up Regularly">Delete unused files to reclaim storage instantly</Step>

  <Step title="Choose Efficient Formats">
    * WebP for images (best compression) - MP4 (H.264) for videos - Avoid BMP, TIFF, or uncompressed
      formats
  </Step>
</Steps>

### Optimize Operations

<Steps>
  <Step title="Batch Uploads">
    Upload multiple files in one request instead of separate API calls
  </Step>

  <Step title="Cache Locally">Don't re-upload files that haven't changed</Step>

  <Step title="Leverage Views">
    Views are 10x cheaper than uploads. Link to files instead of re-uploading.
  </Step>

  <Step title="Monitor Usage">Check dashboard regularly to avoid hitting limits</Step>
</Steps>

## Tier Limits Reference

Quick reference for all tiers:

| Tier     | Storage | Operations/mo | Class A Weight | Class B Weight | 30D Key Price |
| -------- | ------- | ------------- | -------------- | -------------- | ------------- |
| Free     | 1 GB    | 10,000        | 1.0            | 0.1            | \$0           |
| Starter  | 5 GB    | 100,000       | 1.0            | 0.1            | \$2.49        |
| Pro      | 10 GB   | 1,000,000     | 1.0            | 0.1            | \$6.99        |
| Business | 200 GB  | 5,000,000     | 1.0            | 0.1            | \$16.99       |

<Info>Need custom limits? Business tier customers can contact us for enterprise plans.</Info>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="When do operations reset?">
    Operations reset on your billing anniversary. For example, if you subscribed on the 15th,
    operations reset on the 15th of each month. Free tier resets on the 1st of each month.
  </Accordion>

  <Accordion title="Do failed uploads count as operations?">
    No. Only successful operations count toward your limit.
  </Accordion>

  <Accordion title="Do deleted files free up storage immediately?">
    Yes. Deleting a file instantly reclaims its storage space.
  </Accordion>

  <Accordion title="Can I see which files use the most storage?">
    Yes. The dashboard sorts your uploads by file size. Pro/Business users get detailed analytics per
    file.
  </Accordion>

  <Accordion title="What counts as a 'view'?">
    Every time someone accesses your file via CDN URLs, it counts as 0.1 operations. Views from the
    dashboard are not counted to avoid inflating your usage.
  </Accordion>

  <Accordion title="Can I buy additional storage without upgrading?">
    Not currently. Storage and operations are bundled per tier. Consider upgrading if you need more
    capacity.
  </Accordion>

  <Accordion title="What's Imperial's uptime guarantee?">
    Free, Starter, and Pro tiers have a 99.9% uptime target (no SLA). Business tier includes a 99.99%
    uptime SLA guarantee. Check our real-time status at status.imperial.gay
  </Accordion>

  <Accordion title="What's the typical API response time?">
    Imperial is optimized for speed with health checks under 2ms average response, file uploads
    between 300-800ms for images (varies for videos), and CDN delivery under 50ms globally at 95th
    percentile. Load tested at 100+ concurrent users with 0% error rate.
  </Accordion>
</AccordionGroup>

## System Status

<Card title="View Live Status" icon="chart-line" href="https://status.imperial.gay">
  Real-time monitoring powered by BetterStack. Check API health, uptime history, and incident
  reports.
</Card>

## Need More Capacity?

<CardGroup cols={2}>
  <Card title="View Pricing" icon="dollar-sign" href="/pricing">
    Compare all tiers and features
  </Card>

  <Card title="Upgrade Now" icon="arrow-up" href="https://shop.imperial.gay">
    Instant activation, no downtime
  </Card>
</CardGroup>