Usage
Plan, limits and current usage for the calling key's project, so an agent can check quota before a bulk upload.
The Usage object
Properties
| Property | Type | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
plan | string | |||||||||||||||||||||||||||||||
period | string | Current UTC month ( | ||||||||||||||||||||||||||||||
resets_at | string (date-time) | Start of the next UTC month, when monthly counters reset. | ||||||||||||||||||||||||||||||
usage | object | |||||||||||||||||||||||||||||||
Child properties of | ||||||||||||||||||||||||||||||||
| Property | Type | Description |
|---|---|---|
storage_bytes | integer | Total stored bytes in the project. |
uploads | integer | Uploads this month. |
limitsPlan limits: Free 200 MB storage, 500 uploads and 1 GB bandwidth a month; Starter 5 GB, 25,000 and 25 GB; Pro 25 GB, 50,000 and 50 GB.
Child properties of limits
| Property | Type | Description |
|---|---|---|
storage_bytes | integer | Storage cap. |
uploads_per_month | integer | Monthly upload cap. |
bandwidth_bytes_per_month | integer | Monthly CDN bandwidth cap. |
transforms_per_month | integer | Monthly unique-transform cap per project (1,000 Free, 5,000 Starter, 20,000 Pro). |
remainingChild properties of remaining
| Property | Type | Description |
|---|---|---|
storage_bytes | integer | Storage left (floored at 0). |
uploads | integer | Uploads left this month (floored at 0). |
bandwidthMonthly CDN bandwidth measurement. Null is unknown, never zero. The current backend returns unavailable because its approximate CDN counter is not reliably readable here. available permits numeric zero; unlimited uses null limit/remaining; delayed freshness means measured_at predates the request.
Child properties of bandwidth
| Property | Type | Description |
|---|---|---|
status | string | |
used | integer nullable | Bytes accounted in this period, or null when unknown/not applicable. |
remaining | integer nullable | Bytes left, or null when unknown/unlimited. |
limit | integer nullable | Monthly byte limit, or null only when status is unlimited. |
unit | string | |
accounting_period | string | |
resets_at | string (date-time) | |
measured_at | string (date-time) nullable | When |
freshness | string |
generationAI image-generation credits (generate_image) for the current month: 10 Free, 300 Starter, 1,500 Pro.
Child properties of generation
| Property | Type | Description |
|---|---|---|
credits_used | integer | |
credits_limit | integer | Monthly generation credit grant for the plan. |
credits_remaining | integer | Generation credits left this month (floored at 0). |
editingNatural-language image-edit credits (edit_image) for the current month: 5 Free, 100 Starter, 500 Pro.
Child properties of editing
| Property | Type | Description |
|---|---|---|
credits_used | integer | |
credits_limit | integer | Monthly edit credit grant for the plan. |
credits_remaining | integer | Edit credits left this month (floored at 0). |
video_optimizationSocial-ready video source seconds reserved in the current month (optimize_video): 120 Free, 1,800 Starter, 7,200 Pro.
Child properties of video_optimization
| Property | Type | Description |
|---|---|---|
seconds_used | integer | |
seconds_limit | integer | |
seconds_remaining | integer |
video_enrichmentShared media-enrichment source seconds reserved by video transcript/storyboard (enrich_video) and audio transcription (enrich_audio) jobs in the current month: 120 Free, 1,800 Starter, 7,200 Pro.
Child properties of video_enrichment
| Property | Type | Description |
|---|---|---|
seconds_used | integer | |
seconds_limit | integer | |
seconds_remaining | integer |
{
"plan": "free",
"period": "2026-11",
"resets_at": "2026-12-01T00:00:00.000Z",
"usage": {
"storage_bytes": 1048576,
"uploads": 12
},
"limits": {
"storage_bytes": 209715200,
"uploads_per_month": 500,
"bandwidth_bytes_per_month": 1073741824,
"transforms_per_month": 1000
},
"remaining": {
"storage_bytes": 208667000,
"uploads": 488
},
"bandwidth": {
"status": "unavailable",
"used": null,
"remaining": null,
"limit": 1073741824,
"unit": "bytes",
"accounting_period": "2026-11",
"resets_at": "2026-12-01T00:00:00.000Z",
"measured_at": null,
"freshness": "unavailable"
},
"generation": {
"credits_used": 1,
"credits_limit": 10,
"credits_remaining": 9
},
"editing": {
"credits_used": 1,
"credits_limit": 5,
"credits_remaining": 4
},
"video_optimization": {
"seconds_used": 30,
"seconds_limit": 120,
"seconds_remaining": 90
},
"video_enrichment": {
"seconds_used": 42,
"seconds_limit": 120,
"seconds_remaining": 78
}
}Get plan, limits and usage
GET /v1/usage
Plan, limits and current usage for the calling key's project, so an agent can check quota before a bulk upload. Requires a secret key; scoped to that key's project (limits and credits belong to the account).
Storage is cumulative; uploads, generation and edit credits, video optimization seconds and shared media-enrichment seconds use the current UTC month and reset at resets_at. video_enrichment is the backward-compatible field name for the shared media-enrichment allowance consumed by video transcript/storyboard jobs and audio transcription jobs.
bandwidth always carries the real limit, byte unit, accounting period and reset, but currently reports status: unavailable with null used/remaining: the CDN's approximate counters are not reliably readable by the API. Null means unknown, never zero. Unique-transform usage is also unavailable. A usage check neither reserves capacity nor guarantees that a future CDN request will serve.
Plan quotas (storage, monthly uploads, private assets) are refused with 402, not 429: retrying cannot succeed until you delete media, upgrade, or the month resets. Per-plan limits are on Rate limits & quotas.
Authentication
API key, sent as Authorization: Bearer <key>.
Responses
- 200
Usage
- 401
missing_api_key: noAuthorizationheader.invalid_api_key: the header is notBearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked. - 403
publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key.account_suspended: the account is suspended. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl https://api.pixelvault.dev/v1/usage \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": {
"plan": "free",
"period": "2026-11",
"resets_at": "2026-12-01T00:00:00.000Z",
"usage": {
"storage_bytes": 1048576,
"uploads": 12
},
"limits": {
"storage_bytes": 209715200,
"uploads_per_month": 500,
"bandwidth_bytes_per_month": 1073741824,
"transforms_per_month": 1000
},
"remaining": {
"storage_bytes": 208667000,
"uploads": 488
},
"bandwidth": {
"status": "unavailable",
"used": null,
"remaining": null,
"limit": 1073741824,
"unit": "bytes",
"accounting_period": "2026-11",
"resets_at": "2026-12-01T00:00:00.000Z",
"measured_at": null,
"freshness": "unavailable"
},
"generation": {
"credits_used": 1,
"credits_limit": 10,
"credits_remaining": 9
},
"editing": {
"credits_used": 1,
"credits_limit": 5,
"credits_remaining": 4
},
"video_optimization": {
"seconds_used": 30,
"seconds_limit": 120,
"seconds_remaining": 90
},
"video_enrichment": {
"seconds_used": 42,
"seconds_limit": 120,
"seconds_remaining": 78
}
}
}