Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

API reference

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

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) 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) 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): 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) and audio transcription (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.

Authentication

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

Responses

  • 200

    Usage

  • 401

    missing_api_key: no Authorization header. 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: 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. Honour Retry-After.

Request
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
    }
  }
}