---
title: "The account's plan, videos used and remaining this month, clips per video, capabilities, and whether finalize will auto-clip"
method: GET
path: "/api/v1/usage"
---

# The account's plan, videos used and remaining this month, clips per video, capabilities, and whether finalize will auto-clip

`GET /api/v1/usage`

## Request

- Base URL: `https://everpop.app`
- URL: `https://everpop.app/api/v1/usage`
- Auth: HTTP bearer

Read this before planning a batch or starting a render: every clip job uses one video of the monthly allowance, except the first render of a video in a month whose only clip repeats a moment already clipped (qcWarnings flag repeat_moment) or whose clips all end on a held final frame (open_ending), which hands its video back; a video gets one such uncharged render a month, whichever kind came first. Tell the user how many videos remain.

## Response `200`

The plan and allowance.

- UsageEnvelope
  - `ok` unknown, required
  - `data` object, required
    - `plan` 'free' | 'starter' | 'pro' | 'scale', required
    - `videos` object, required
      - `used` integer, required: Videos used in the current monthly window (every clip job counts as one; refunded failures don't).
      - `limit` integer, nullable, required
      - `remaining` integer, nullable, required
      - `resetsAt` string, date-time, required: When the monthly window resets (the billing day for paid plans).
    - `clipsPerVideo` integer, required: The cap applied to clipCount on POST /api/v1/clip.
    - `capabilities` object, required
      - `apiAccess` boolean, required
      - `autoPost` boolean, required
      - `campaigns` boolean, required
      - `fourK` boolean, required
      - `customFonts` boolean, required
    - `destinationsConnected` integer, required: Connected destinations whose grant is live (not waiting for a reconnect): the same set GET /api/v1/publish lists.
    - `autoClipOnFinalize` boolean, required: Whether POST /api/v1/videos/complete (renderMode auto) starts a render right now: automatic clipping is on, the plan is active and videos remain.

## Other responses

- `401`: The API key did not authenticate. code=key_missing: no Authorization: Bearer epk_... header. code=key_invalid: the key is unknown or revoked. code=key_expired: the key passed its expiry; the user creates a new one in Dashboard → API.
- `402`: REST and MCP need the Pro or Scale plan. reason=subscription: the account has no active subscription (subscribe, or redeem an invite code). reason=plan: the account's plan doesn't include this (API and agent access need Pro or Scale).
- `403`: code=scope (also reason=scope): the API key is read-only and this is a write. code=suspended: the account is suspended. Endpoint-specific refusals document their own reason.
- `429`: Too many requests. code=rate_limited: the per-minute limit; wait Retry-After (60) seconds. code=quota_exhausted (with used, limit, resetsAt, retryable: false): the monthly allowance is used up; Retry-After is the seconds until resetsAt — tell the user rather than wait. code=queue_capacity (retryable: true): the render queue is full; retry after Retry-After (180).

---

[API](https://skmtc.dev/everpop/apis/everpop-api.md) · [All operations](https://skmtc.dev/everpop/apis/everpop-api/llms.txt) · [OpenAPI document](https://skmtc.dev/everpop/apis/everpop-api/revisions/1a9fb20867f5?raw)