Rate Limits

Request, batch, and concurrency limits for the Knowlify HTTP API

Overview

Knowlify enforces four independent limits on the HTTP API. Each is keyed per caller — personal users have their own pool; each organization has its own pool.

Limit	Value	Behavior on excess
Videos request rate	30 requests / 60 s on POST /v1/videos and GET /v1/videos/{uuid}	429 Too Many Requests
Edits request rate	10 requests / 60 s on POST /v1/edits, GET /v1/edits/{edit_id}, POST /v1/edits/{edit_id}/revert	429 Too Many Requests
Batch size	1–50 items per POST /v1/videos	400 Bad Request
Concurrent jobs	3 active jobs per caller	Excess items are parked (queued for promotion)

Request rate

A fixed 60-second window per caller, counted in Redis. The identity used for keying is:

• user_id for personal calls (JWT or personal API key)
• org:<id> for organization calls (org API key, or JWT with org_id in body)

Every successful response includes the current window state:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 42

• X-RateLimit-Limit — the cap (30)
• X-RateLimit-Remaining — requests left in the current window
• X-RateLimit-Reset — seconds until the window resets

When you exceed the cap, the response is 429 with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 45
Content-Type: application/json

{ "detail": "Rate limit exceeded: 30 requests per 60s. Retry in 45s." }

Use X-RateLimit-Remaining to self-pace. If a single 50-item batch is fine for your workload, prefer one batched call over 50 single-item calls.

Separate bucket for edits

The /v1/edits endpoints have their own counter (10 requests / 60 s by default), independent from the /v1/videos 30 / 60 s bucket. Edits are typically cheaper than full renders but submitted more frequently, so the two limits don’t share state — bursting on /v1/edits won’t eat your /v1/videos quota. The same per-caller identity (user_id or org:<id>) keys both buckets.

Batch size

A single POST /v1/videos request must contain between 1 and 50 entries in the videos array. The server rejects empty arrays and arrays of more than 50 items with 400 and a Pydantic validation error in detail.

Concurrent jobs

Each caller may have up to 3 jobs actively rendering at any moment. When you submit more than 3 items in a single batch (or submit while you already have jobs in flight), excess items are accepted but marked "parked":

{
  "index": 4,
  "uuid": "...",
  "status": "parked",
  "queue_position": 2
}

The Knowlify worker promotes parked jobs in FIFO order as active slots free up — there’s nothing for you to retry. Poll GET /v1/videos/{uuid} to watch the job advance from pending → queued → rendering stages.

Personal and organization pools are independent. A user who is also an org admin can have 3 personal jobs and 3 org jobs running concurrently.

Need higher limits?

Email [e-mail] with your account ID and expected volume.