Usage

GET /v1/usage

Get your current video-minute consumption, plan limits, and a per-operation breakdown for the billing period.

Example

curl https://api.vidocu.ai/v1/usage \
  -H "Authorization: Bearer vdo_live_your_key_here"

Response 200 OK

{
  "plan": "business",
  "billingModel": "credits",
  "period": {
    "start": "2026-06-01T00:00:00.000Z",
    "end": "2026-07-01T00:00:00.000Z"
  },
  "balance": {
    "unit": "credits",
    "used": 45.3,
    "limit": 60,
    "remaining": 14.7
  },
  "videoMinutes": {
    "used": 45.3,
    "limit": 60,
    "remaining": 14.7
  },
  "breakdown": {
    "apiCalls": 1542,
    "videoMinutes": 45.3,
    "exports": 12,
    "analyses": 28,
    "translations": 5,
    "helpArticles": 8,
    "voiceovers": 3,
    "toolExecutions": 4
  },
  "limits": {
    "videoMinutes": 60,
    "maxVideoDuration": 10,
    "requestsPerMinute": 60
  }
}

Response fields

Field	Type	Description
plan	string	Your Vidocu plan: free, pro, business, or enterprise
billingModel	string	credits or minutes - which unit this workspace spends
period.start	string	Billing period start
period.end	string | null	Billing period end (null for free/lifetime tracking)
balance.unit	string	credits or minutes - the unit of the three fields below
balance.used	number	Amount used this period (shared with the app)
balance.limit	number	Monthly allowance (-1 = unlimited)
balance.remaining	number | null	Left this period (null when unlimited)
videoMinutes	object	Deprecated - same numbers as balance, but the name says "minutes" regardless of your actual unit. Use balance.
breakdown	object | null	Per-operation API call counts (analytics only, not a billing source)
limits.videoMinutes	number	Monthly video minute limit (-1 = unlimited)
limits.maxVideoDuration	number	Max minutes per single video (-1/0 = unlimited)
limits.requestsPerMinute	number	Requests per minute (fixed at 60)

info

balance is the meter the API enforces against, and it's the same allowance the Vidocu app uses. Most workspaces are billed in credits, so check balance.unit before you label the number - the legacy videoMinutes block carries the same values under a name that only tells the truth on grandfathered minutes plans. The breakdown object is a per-operation tally for your own analytics.

Errors

Status	Code	Cause
401	authentication_error	Invalid or missing API key
403	limit_exceeded	Monthly video-minute allowance used up

---

Credit costs

GET /v1/usage/credits

What each operation costs, alongside your balance - so you can price work before starting it rather than discovering the cost afterwards.

Example

curl https://api.vidocu.ai/v1/usage/credits \
  -H "Authorization: Bearer vdo_live_your_key_here"

Response 200 OK

{
  "plan": "business",
  "billingModel": "credits",
  "balance": { "unit": "credits", "used": 45, "limit": 6000, "remaining": 5955 },
  "operations": [
    {
      "operation": "video_analysis",
      "endpoint": "POST /v1/videos/:id/analyze",
      "unit": "minute",
      "credits": 50,
      "bundled": false,
      "perLanguage": false
    },
    {
      "operation": "translation",
      "endpoint": "POST /v1/videos/:id/translate",
      "unit": "minute",
      "credits": 8,
      "bundled": false,
      "perLanguage": true
    },
    {
      "operation": "help_article",
      "endpoint": "POST /v1/videos/:id/article",
      "unit": "run",
      "credits": 0,
      "bundled": true,
      "perLanguage": false
    }
  ],
  "note": "Costs are in credits. A per-minute operation bills ceil(minutes x rate)."
}

Reading it

Field	Meaning
unit	minute bills per minute of video, run is a flat charge per call
credits	Cost per unit
bundled	true means it's covered by the paid analysis and never charged separately
perLanguage	true means the cost multiplies by the number of target languages

Per-minute costs round up, so a 90-second analysis at 50 credits/minute bills 75, and any partial minute bills at least one.

Tools aren't listed here - each bills at its own rate. List Tools is the catalogue, and a tool run is charged when it succeeds.

Errors

Status	Code	Cause
401	authentication_error	Invalid or missing API key
403	insufficient_scope	Token lacks usage:read