Skip to content

Bandwidth & Degradation

Bandwidth is the monthly CDN egress — the amount of bytes Picora’s CDN serves to your viewers when they access your images and videos. It’s separate from upload (in-bound) bandwidth, which is unmetered.

This is one of the most-asked-about features. v0.10.0 introduced the modern bandwidth tracking and degradation system.

How bandwidth is measured

Viewer requests https://media.picora.me/abc.png
       ↓
   CDN serves the file
       ↓
   Edge logs the request size
       ↓
   Hourly cron aggregates per user
       ↓
   quota:img_bandwidth:{userId}:{YYYY-MM} += bytes

For video / audio, Bunny.net (overseas) and Aliyun VOD (mainland) report total bandwidth which we attribute back to individual users by storage ratio — every hour, a cron job reads the provider’s bandwidth report and divides it across users proportionally to their storage usage.

This means:

  • A user with 10% of total storage is charged 10% of total bandwidth that hour
  • Cache misses cause higher bandwidth than direct downloads (encoded headers + chunks)
  • The estimate is within ~5% of the underlying provider’s actual numbers

Reading bandwidth in the dashboard

The Dashboard → Usage shows:

  • Image bandwidth card: This month’s usage / monthly limit, with a 6-month sparkline
  • Video bandwidth card: Same, plus a status badge:
    • 🟢 OK — under quota, full quality playback
    • 🟡 Degraded — 100-120% used, auto-360p mode
    • 🔴 Suspended — over 120%, playback returns HTTP 451

The 360p auto-degrade strategy {#degrade-strategy}

When monthly video bandwidth exceeds 100% of your plan’s limit:

  1. The user’s quota:video_status cache key flips to "degraded"
  2. Subsequent video playback requests get a modified HLS playlist with only 360p tracks
  3. Existing playback sessions continue at original quality (no mid-stream interruption)
  4. New sessions start at 360p

This is intentional design — we don’t cut off your viewers entirely, but the visible quality drop is meant to surface the issue to you (creator) for natural upgrade pressure.

When you upgrade or the next month rolls over:

  • quota:video_status flips back to "ok"
  • Full quality returns within 1-2 minutes (cache propagation)

The suspend strategy

When usage exceeds 120%:

  • Status flips to "suspended"
  • Video playback returns HTTP 451 Unavailable for Legal Reasons with a JSON body explaining the situation
  • Audio playback continues (same media bandwidth pool, but smaller)
  • Image / Markdown access unaffected

Why 120% rather than 100%? — to give a transition zone before full cutoff, so a sudden viral moment doesn’t immediately kill your service. The 100-120% degraded zone is the warning shot.

Bandwidth alerts

Picora emails you at:

  • 80% of monthly limit (info; can be disabled in Profile → Notifications)
  • 100% of limit (warning; mandatory)
  • 120% of limit, video only (suspended; mandatory)

Subject lines start with "Picora —" and include action prompts (upgrade link, billing portal).

Mitigation strategies

If you’re approaching limits and don’t want to upgrade yet:

Reduce egress

  • Embed thumbnails instead of full-resolution images on listing pages
  • Add lazy loading: <img loading="lazy">
  • Use srcset to serve smaller images on smaller screens
  • For videos: prefer HLS (lower bandwidth than MP4 download) and let viewers control quality

Anti-hotlinking

If your bandwidth spike comes from third parties hotlinking your images:

  1. Set is_public=false on private resources
  2. For public images, set up Referer-based hotlink protection (admin) — coming as a self-serve feature in v0.20+

CDN cache hits

The more your CDN cache hits, the lower your bandwidth. Picora uses a 24-hour edge cache by default. Frequently-changing content (uncommon) reduces hit ratio.

Bandwidth API (programmatic access)

Use GET /v1/user/me/usage to fetch current bandwidth status:

{
  "success": true,
  "data": {
    "image": {
      "storage": { "used": 524288000, "limit": 5368709120 },
      "bandwidth": { "used": 1073741824, "limit": 5368709120, "monthYear": "2026-04" }
    },
    "video": {
      "storage": { "used": 5368709120, "limit": 10737418240 },
      "bandwidth": { "used": 9663676416, "limit": 10737418240, "monthYear": "2026-04" },
      "status": "degraded"
    },
    "doc": {
      "count": { "used": 247, "limit": 1000 }
    }
  }
}

Common questions

Why does my bandwidth keep climbing even when nobody’s looking at my site? — Likely culprits: your own page reloads counting as views (especially with cache-busting query params), search engine crawlers hitting public images, social media link previews fetching images. Check your analytics for traffic sources.

Bandwidth shows 95% but it’s only the 15th of the month — am I going to get cut off? — Yes, you should expect to hit 100% around day 15-16 at this pace. Either upgrade now, reduce egress, or accept the 360p mode for the rest of the month.

Can I get a refund if I hit the bandwidth wall mid-month? — No, bandwidth is not refundable. But you can upgrade pro-rated mid-cycle to immediately restore full quality.