> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knowlify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={null}
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." }
```

<Tip>
  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.
</Tip>

### 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"`:

```json theme={null}
{
  "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}`](/api-reference/poll-video) to watch the job advance from `pending` → `queued` → rendering stages.

<Note>
  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.
</Note>

## Need higher limits?

Email [info@knowlify.com](mailto:info@knowlify.com) with your account ID and expected volume.