<!-- Markdown twin of https://pixelvault.dev/docs/api/usage/ -->

[API reference](/docs/api/)

# 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](#object)
-   GET [Get plan, limits and usage](#get_usage)

## The Usage object

### Properties

The Usage object properties

Property

Type

Description

`plan`

string

One of: `free`, `starter`, `pro`

`period`

string

Current UTC month (`YYYY-MM`).

`resets_at`

string (date-time)

Start of the next UTC month, when monthly counters reset.

`usage`

object

Child properties of `usage`

Properties of usage

Property

Type

Description

`storage_bytes`

integer

Total stored bytes in the project.

`uploads`

integer

Uploads this month.

`limits`

object

Plan 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`

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).

`remaining`

object

Child properties of `remaining`

Properties of remaining

Property

Type

Description

`storage_bytes`

integer

Storage left (floored at 0).

`uploads`

integer

Uploads left this month (floored at 0).

`bandwidth`

object

Monthly 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`

Properties of bandwidth

Property

Type

Description

`status`

string

One of: `available`, `unavailable`, `unlimited`

`used`

integer nullable

Bytes accounted in this period, or null when unknown/not applicable.

min 0

`remaining`

integer nullable

Bytes left, or null when unknown/unlimited.

min 0

`limit`

integer nullable

Monthly byte limit, or null only when status is unlimited.

min 0

`unit`

string

One of: `bytes`

`accounting_period`

string

pattern ^\\d{4}-\\d{2}$

`resets_at`

string (date-time)

`measured_at`

string (date-time) nullable

When `used` was measured; null when unavailable.

`freshness`

string

One of: `near_real_time`, `delayed`, `unavailable`, `not_applicable`

`generation`

object

AI image-generation credits ([`generate_image`](/docs/api/images/#generate_image)) for the current month: 10 Free, 300 Starter, 1,500 Pro.

Child properties of `generation`

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).

`editing`

object

Natural-language image-edit credits ([`edit_image`](/docs/api/images/#edit_image)) for the current month: 5 Free, 100 Starter, 500 Pro.

Child properties of `editing`

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_optimization`

object

Social-ready video source seconds reserved in the current month ([`optimize_video`](/docs/api/videos/#optimize_video)): 120 Free, 1,800 Starter, 7,200 Pro.

Child properties of `video_optimization`

Properties of video\_optimization

Property

Type

Description

`seconds_used`

integer

`seconds_limit`

integer

`seconds_remaining`

integer

`video_enrichment`

object

Shared media-enrichment source seconds reserved by video transcript/storyboard ([`enrich_video`](/docs/api/videos/#enrich_video)) and audio transcription ([`enrich_audio`](/docs/api/audio/#enrich_audio)) jobs in the current month: 120 Free, 1,800 Starter, 7,200 Pro.

Child properties of `video_enrichment`

Properties of video\_enrichment

Property

Type

Description

`seconds_used`

integer

`seconds_limit`

integer

`seconds_remaining`

integer

The Usage object

```
{
  "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](https://pixelvault.dev/docs/limits/).

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Responses

-   200
    
    Usage
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl https://api.pixelvault.dev/v1/usage \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "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
    }
  }
}
```
