Usage and quota

Check how much of your monthly limit you've used.

Examples use VIDEO_ID and clp_live_... as placeholders.

Read your usage

Call GET /v1/usage:

curl -X GET "https://clypso-eta.vercel.app/v1/usage" \
  -H "Authorization: Bearer clp_live_..."

JSON

{
  "used": 0,
  "limit": 30,
  "remaining": 30,
  "period": "2026-11",
  "request_id": "REQUEST_ID"
}

Field	Meaning
`used`	Videos counted so far this month.
`limit`	Your monthly limit.
`remaining`	`limit` minus `used`.
`period`	The current month in UTC, as `YYYY-MM`.
`request_id`	This request's ID.

Reading your usage doesn't use any of your monthly limit. It does count toward the rate limit of 60 a minute.

What counts

A successful extraction that isn't cached counts as one video.
A cached result doesn't count.
A failed run doesn't count. A run in progress holds one video, and gives it back if it fails.
All keys on your account share one monthly limit.

The monthly reset

During early access the limit is 30 videos a month. The count resets at the start of each calendar month, at 00:00 UTC on the first, whenever you signed up.

When you reach the limit

A request that would run a new extraction returns a 200 with ok: false and the code quota_exceeded, or error_code on a job. Cached results keep working. New extractions work again after the monthly reset.

Daily capacity

Clypso also has a daily capacity, shared by everyone using the service. When it's reached, new extractions pause until 00:00 UTC, even if you have monthly videos left. A request that would run one returns a 200 with ok: false and the code spend_ceiling_reached, or error_code on a job:

Daily extraction capacity has been reached. It resets at 00:00 UTC.

Cached results keep working, and the refused request doesn't count against your monthly limit. error.retryable is false, so try again after the reset rather than in a loop.