Limits
A limit caps what one request may ask of the server: the pages of a document it reads, the text it carries, the size of an image, the length of its audio, the images of a chat, how long its job runs, how many jobs a key keeps running. Past a limit the request is refused before any work, or reads the part the limit allows (the first pages, the start of the text, the image scaled down) and says so. Nothing is ever cut silently: every response lists the limits that bound it.
Limits are set on the console's Documents › Limits page and apply to the next request, on every node of a farm.
1Who sets a limit#
Each limit resolves, for one request, from the most specific level that states it:
| Level | States | Example |
|---|---|---|
| Server | The default of every request | 200 pages per document |
| Operation | Its own requests, higher or lower than the server | Structured extraction reads 20 pages; document OCR 500 |
| Key group | Every key of the group (groups are made on Access) | A partner tier reads 1,000 pages |
| Key | That key alone | A trial key reads 5 pages |
| Request | That request alone, lower only | max_pages: 4 |
The value, the action and whether callers may choose each resolve on their own: a key group can raise
the value while the operation's action still applies. A request may lower a page limit with
max_pages, never raise it.
2What happens past a limit#
| Action | Answer |
|---|---|
reject |
413 with the reason limit_exceeded and the limit in the error body, before any page is rendered, recognized or read. A refusal never becomes a job. |
truncate |
The request runs on the part the limit allows and lists the limit in limits_applied. Page numbers keep their meaning: page 3 of the part is page 3 of the document. |
When no level states an action, a page or text limit reads the first part for the operations whose question the opening pages answer (structured extraction, classification, language detection) and refuses the operations whose answer covers the whole document (summarization, translation, entity and PII detection, Markdown conversion, parsing, OCR), where a partial answer would read as complete.
When a limit lets callers choose (the default for limits that offer both actions), a request picks with
on_limit. When the operator turns the choice off, a request that asks for the other action is
refused with 400 and the reason on_limit_not_allowed, even below the limit, so an integration
learns the policy at its first call.
3The request#
Every operation that reads a document takes two optional fields:
| Field | Meaning |
|---|---|
max_pages |
Read only the first N pages. A value above the server's limit does not raise it. |
on_limit |
reject or truncate, when the limit lets callers choose. |
POST /lmkit/v1/extract-structured-data
{
"input": "9f2c0d...",
"input_format": "FileIdentifier",
"json_schema": { "type": "object", "properties": { "vendor": { "type": "string" } } },
"max_pages": 4,
"on_limit": "truncate"
}
4The response#
A response whose input was read in part carries limits_applied at the root of its body, beside
usage, and the X-LMKit-Limits-Applied header; a job carries it in its final status.
{
"json": "{...}",
"usage": { "...": "..." },
"limits_applied": [
{ "limit": "pages_per_document", "value": 4, "actual": 172, "unit": "pages",
"action": "truncated", "scope": "request", "operation": "extract-structured-data" }
]
}
X-LMKit-Limits-Applied: pages_per_document=4;actual=172;action=truncated;scope=request
A refusal names the limit in its error body:
{
"error": {
"message": "The document has 172 pages; the server's limit reads at most 20. Send on_limit \"truncate\" to read the part it allows.",
"type": "limit_exceeded",
"param": "max_pages",
"limit": { "limit": "pages_per_document", "value": 20, "actual": 172, "unit": "pages",
"action": "rejected", "scope": "server", "operation": "extract-structured-data" }
}
}
action is truncated, rejected or stopped; scope is the level that set the value: server,
operation, key_group, key or request.
5Reading your limits#
GET /lmkit/v1/limits answers, for the key that authenticates the request, every limit that applies to
it: its value, its action, whether the request may choose, the level that set it, and the value of each
operation for the limits measured per operation. A client can trim its own input before sending it.
6The limits#
| Limit | Unit | Actions | Per operation | Per key group and key |
|---|---|---|---|---|
pages_per_document |
pages | reject, truncate | yes | yes |
characters_per_document |
characters | reject, truncate | yes | yes |
megapixels_per_image |
megapixels | reject, truncate | yes | yes |
audio_minutes |
minutes | reject, truncate | no | yes |
images_per_request |
images | reject | no | yes |
file_size |
bytes | reject | no | no |
time_per_request |
seconds | reject | yes | yes |
unclaimed_job_results |
minutes | reject | no | yes |
jobs_in_flight |
jobs | reject | no | yes |
- Pages per document is counted before any page is rendered. A PDF is cut directly; any other paged format (an office document, a multi-page image, an e-mail) is read in part through its PDF rendering. A format that cannot be read in part is refused, with a message that says so.
- Text per document counts the text a document carries (its text layer, or the text sent). Text recognized on scans is not counted: the page limit bounds scans. Read in part, a paged document keeps the leading pages whose text fits; a text keeps its start, cut on a word.
- Image size applies to an image sent as the document. Read in part, the image is scaled down to the limit.
- Audio length is measured once the audio is decoded, before the speech model runs. Read in part, the first minutes are transcribed.
- Images per request counts the images a chat request hands a vision model, on every API dialect, and refuses the request before any image is encoded.
- File size is the server's upload limit (the
max_file_upload_size_bytessetting), the same for every caller. - Time per request stops a document request's work once it runs past the limit; its job fails with
408andlimit_exceeded. - Unclaimed job results stops a job handed back as a
202whose status nobody asked for within the limit, so a client that gave up does not keep the server busy for nothing. On a farm, a poll answered by another node counts. - Jobs in flight per key refuses a new request with
429andRetry-Afterwhile the key already has that many running. Its server value is themax_jobs_per_ownersetting; on a farm it is shared out among the live nodes.
7Measuring before you change a limit#
Each row of the Limits page shows what the limit did in the last 7 days: requests read in part, refused, stopped. The editor's Measure on the last 7 days re-evaluates the recent requests against the settings in the editor, without saving them, so the effect of a new value is known before it applies.