Skip to main content

​
Overview

Knowlify enforces three independent limits on the HTTP API. Each is keyed per caller — personal users have their own pool; each organization has its own pool.
LimitValueBehavior on excess
Request rate30 requests / 60 s429 Too Many Requests
Batch size1–50 items per POST /v1/videos400 Bad Request
Concurrent jobs3 active jobs per callerExcess 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.

​
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 [email protected] with your account ID and expected volume.