Usage & Tracking
Tenantbox tracks storage usage automatically as files are uploaded and deleted. Query usage per tenant, aggregate across your project, and surface the data in your own dashboards.
What Tenantbox tracks
Storage used
Total bytes stored per tenant. Updated automatically on every upload and deletion.
File count
Number of confirmed uploaded files per tenant. Only counts files that successfully reached Tenantbox storage.
Quota consumption
How much of the tenant's storage limit has been consumed, expressed as a byte value and as a percentage.
File timestamps
Every file record has a created_at timestamp so you can build time-series views of upload activity.
Get usage for a single tenant
The most common use case — fetch current storage stats for one of your users to display in their account page or settings panel.
curl -X GET "https://api.tenantbox.dev/api/storage/tenants/user_123/usage/" \
-H "Authorization: Bearer sk_live_xxx"{
"tenant_id": "user_123",
"email": null,
"storage_used_bytes": 10485760,
"storage_limit_bytes": 524288000,
"total_files": 4
}Aggregate usage across all tenants
Tenantbox doesn't have a bulk summary endpoint yet — aggregate total usage by fetching each tenant and summing on your side. Store your tenant IDs in your own database and loop over them. Fetching in parallel keeps this fast.
# Tenantbox does not have a bulk list endpoint yet —
# fetch usage per tenant and aggregate on your side.
# Store tenant IDs in your own database and loop over them.
for tenant_id in user_001 user_002 user_003; do
curl -s "https://api.tenantbox.dev/api/storage/tenants/${tenant_id}/usage/" \
-H "Authorization: Bearer sk_live_xxx"
echo ""
doneUsage response fields
| Field | Type | Description |
|---|---|---|
tenant_id | string | Your user's ID — the external_tenant_id passed at upload time. |
email | string | null | Optional email address for the tenant. |
storage_used_bytes | integer | Current total bytes stored for this tenant. Updated automatically on upload and deletion. |
storage_limit_bytes | integer | null | The tenant's quota in bytes. null means no limit is set. |
total_files | integer | Number of confirmed uploaded files. Pending uploads not yet confirmed are excluded. |
Usage in the dashboard
You don't have to use the API to monitor usage. The Tenantbox dashboard shows per-project and per-tenant storage usage, file counts, and quota consumption in real time. Use the dashboard for operational monitoring and the API to surface data inside your own product.
Project overview
Total tenants, files, and storage used across your entire project at a glance.
Per-tenant view
Drill down into any tenant to see their files, storage used, and quota status.
Storage bars
Visual storage bars with colour-coded health — green, yellow, and red by consumption percentage.
Best practices
Fetch fresh data when showing usage meters. Don't cache usage indefinitely — stale numbers confuse users when they've just uploaded or deleted files.
Fetch in parallel when aggregating. If you need totals across many tenants, use concurrent requests rather than sequential calls to keep response times low.
Store tenant IDs in your own database. Tenantbox doesn't provide a paginated tenant list endpoint yet — you need to maintain the list of your tenant IDs yourself.
Build alerts for high-usage tenants. Periodically poll usage and notify yourself when any tenant exceeds 80% of their quota so you can reach out proactively.
Don't expose raw byte values to end users. Convert bytes to human-readable units (MB, GB) in your UI — raw byte counts are confusing and unhelpful for non-technical users.
You've reached the end of the docs
You now know everything you need to integrate TenantBox — uploading, downloading, deleting, tenant management, quotas, and usage tracking. If you run into anything not covered here, reach out.