Skip to content

Quota Overview

Picora enforces quotas across multiple independent dimensions — going over one does not affect the others. Understand each dimension before subscribing.

Quota dimensions

DimensionWhat it limitsWhen checked
img_storage_bytesTotal bytes of images storedOn every image upload
img_bandwidth_bytesMonthly CDN egress for imagesOn every image external link request
media_storage_bytesCombined video + audio storageOn every video / audio upload
media_bandwidth_bytesMonthly CDN egress for video + audioOn every video / audio playback
doc_count_limitNumber of Markdown documents (not bytes)On every document upload
doc_max_file_bytesSingle Markdown file sizeOn every document upload
doc_max_images_per_docEmbedded image count per MarkdownOn every document upload
uploadsPerDay / uploadsPerMonthThrottle upload count (anti-abuse)On every upload

See plan comparison for actual numbers per tier.

How quota is tracked

Picora maintains real-time counters in the cache layer (Cloudflare KV overseas / Redis mainland). Cache keys:

KeyWhat it stores
quota:img_storage:{userId}Total bytes of images
quota:img_bandwidth:{userId}:{YYYY-MM}Monthly image CDN bytes (TTL 45 days)
quota:video_storage:{userId}Total video bytes
quota:video_bandwidth:{userId}:{YYYY-MM}Monthly video CDN bytes
quota:doc_count:{userId}Total Markdown document count

Counters are decremented when you delete a resource — so freeing up space is immediate.

Reading quota in the dashboard

Open Dashboard → Usage to see:

  • Storage cards for image / video+audio / Markdown — show used vs limit with a progress bar
  • Bandwidth cards for image / video — show monthly used vs limit, plus a 6-month sparkline
  • Upload count — daily and monthly counters

The cards update within 1-2 seconds of any change (no manual refresh needed in most cases).

When you exceed quota

Different dimensions have different consequences:

Storage exceeded

  • Image / video / audio / Markdown: new uploads return 403 QUOTA_EXCEEDED with detail telling you which dimension
  • Existing resources remain accessible — only new uploads are blocked
  • Solution: delete unused resources, or upgrade your plan

Bandwidth exceeded (monthly CDN egress)

  • Image bandwidth: external link requests beyond the limit get throttled. We’re conservative — no hard cutoff in v0.10, but heavy abusers may be temporarily disabled.
  • Video bandwidth: auto-degrades to 360p playback. If usage exceeds 120% of quota, video playback is suspended entirely (HTTP 451) until next month or upgrade. See bandwidth & degradation.
  • Markdown: no bandwidth quota (markdown documents have negligible egress)

Document count exceeded

  • New POST /v1/docs returns 403 QUOTA_EXCEEDED: doc_count
  • Existing documents remain readable / deletable
  • Solution: delete documents you no longer need, or upgrade to a tier with more documents

Upload throttling exceeded

  • New uploads return 429 RATE_LIMIT with Retry-After header
  • Resets at midnight UTC (daily) and start of month (monthly)
  • Different from quota — resets on a clock, not on usage decrease

API responses

When uploading, you can detect quota exhaustion:

Terminal window
$ curl -X POST https://api.picora.me/v1/images \
    -H "Authorization: Bearer sk_live_..." \
    -F file=@photo.jpg


# Response (over quota):
# HTTP/1.1 403 Forbidden
# {
#   "success": false,
#   "error": "Quota exceeded: img_storage",
#   "code": "QUOTA_EXCEEDED",
#   "meta": {
#     "type": "img_storage",
#     "used": 104857600,
#     "limit": 104857600
#   }
# }

Use the code and meta.type fields to programmatically determine the cause and prompt the user appropriately.

Quota alerts

Picora emails you at threshold milestones:

ThresholdEmail subject
80% used”Picora — heads up: 80% of your image storage used”
100% used”Picora — quota exhausted, action needed”
110% bandwidth (video only)“Picora — your video bandwidth is exceeded”
120% bandwidth (video only)“Picora — video playback suspended”

You can opt out of the 80% threshold email but not the 100%+ ones (they’re service-critical).