Reference
Limits
Every size limit, cap and default of the Zaproo Search API in one place, with what happens when you reach it.
How to read this page
These are hard limits of the API: a request past one is refused, usually with 400 VALIDATION_FAILED or 409 and a code naming the limit. They are the same on every plan. Plan quotas (documents, searches a month, indices, seats) are different: they are soft and never block anything. See Plans and billing.
Requests
| Limit | Value | Meaning |
|---|---|---|
| Request body | 100 kB | Every JSON body, except the routes below. |
| Bulk request body | 10 MB | Document upserts and deletes, replace-session uploads, synonym import and /mcp. |
| Idempotency key | 200 characters, kept 24 hours | A retry with the same Idempotency-Key within 24 hours answers the first task instead of running again. |
| List page size | 20 documents, 25 synonyms, 50 tasks by default; 100 at most | The limit query parameter of list routes. |
Indices and mapping
| Limit | Value | Meaning |
|---|---|---|
| Index name | 1 to 100 characters | |
| Fields per mapping | 500 | Including id and every attributes.* field. |
| Field name | Letter first, then letters, digits or _, up to 64 characters | Optionally prefixed with attributes.. |
| Unmapped fields tracked | 1000 | Fields seen in documents but not in the mapping, listed by GET .../mapping. |
| Old versions kept | 24 hours | After a reindex swaps the alias, the previous version stays a day so a bad swap can be undone. |
Documents and tasks
| Limit | Value | Meaning |
|---|---|---|
| Documents per request | 1000 | Upsert and delete batches, and each replace-session upload. |
| Document id | 1 to 512 characters | |
| Validation issues listed | 20 | A 400 on a batch lists at most 20 problems; fix those and send again. |
| Errors kept per task | 1000 | Per-document errors on a PARTIAL or FAILED task. |
| Attempts per document task | 5 | A document write that fails on an infrastructure error is retried up to 5 times, then the task fails. A reindex or a suggestion build runs once. |
| Replace session lifetime | 6 hours | An open session that is not committed within 6 hours is dropped with its building version. |
Search
| Limit | Value | Meaning |
|---|---|---|
| Query length | 500 characters | q in a search request. |
| Page window | 10,000 | page × perPage may not pass 10,000; deeper pages answer 400 PAGE_OUT_OF_RANGE. total counts up to 10,000. |
| Results per page | 24 by default, 100 at most; 1 to 1000 settable per profile | perPage in the request, capped by the profile's perPage.max. |
| Sort clauses | 10 | Per sort option, and in pinnedSort. |
sessionId | 1 to 100 letters, digits, - or _, not starting with _ | |
| Filter values | 1000 per field, 500 characters each | A list filter like {"brand": ["a", "b"]}. |
| Filter groups | 4 levels deep, 100 field filters in all | $or takes 2 to 20 filters, $and 1 to 20, $not one. |
fields | 1 to 100 names | Each must be a field the profile returns. |
excludeIds | 1 to 1000 ids | |
| Hits per MCP search | 10 | search, preview_profile and test_rule over MCP. |
Search profiles and facets
| Limit | Value | Meaning |
|---|---|---|
| Profiles per index | 50 | One more answers 409 PROFILE_LIMIT_REACHED. |
| Profile name | 1 to 100 characters | Unique within an index. |
| Query field weight | Above 0, up to 100 | |
| Phrase boost | 0 to 100 | Default 2. |
| Typo prefix length | 0 to 10 | Default 1. |
| Facets | 50 per index or profile | |
| Facet values | 20 by default, 500 at most (terms); 50 by default, 500 at most (hierarchy) | |
| Range buckets | 1 to 50 per range facet | |
| Sort options | 1 to 50 per profile | |
| Extra filterable fields | 100 per profile | |
| Returned fields | 200 per profile |
Synonyms
| Limit | Value | Meaning |
|---|---|---|
| Synonym rules per index | 10,000 | One more, or an import that would pass it, answers 409 SYNONYM_LIMIT_REACHED. |
| Terms per side | 100 | Terms of an equivalent rule, or each side of a one-way rule. |
| Term length | 100 characters | |
| Import file | 2,000,000 characters | The Solr-format text of POST .../synonyms/import. |
| Query variants | 8 | A query expands to at most 8 synonym variants. |
Ranking rules
| Limit | Value | Meaning |
|---|---|---|
| Rules per index | 1000 | One more answers 409 RULE_LIMIT_REACHED. |
| Queries per rule | 100 | Phrases of up to 200 characters. |
| Actions per rule | 10 | |
| Pinned products | 24 | Per rule, and in total on one search. |
| Hidden products | 500 per rule | |
| Boost factor | 0.1 to 10 | Below 1 buries the products. |
| Profiles per rule | 50 | Empty means every profile. |
Autocomplete
| Limit | Value | Meaning |
|---|---|---|
| Suggest query length | 100 characters | q in a suggest request. |
| Suggestions per answer | 1 to 20, default 8 | |
| Empty-query suggestions | 1 to 20, default 5 | |
| Suggestion fields | 10 | Keyword fields whose values become suggestions. |
| Values per suggestion field | 200 | The most frequent values of each field. |
| Minimum searches | 1 to 1000, default 2 | |
| Lookback | 1 to 90 days, default 30 | |
| Custom suggestions | 1000 per index | One more answers 409 SUGGESTION_LIMIT_REACHED. |
| Custom suggestion text | 100 characters | |
| Custom suggestion weight | Above 0, up to 1,000,000 | |
| Queries with a facet hint | 200 | The most popular queries of each build. |
Analytics
| Limit | Value | Meaning |
|---|---|---|
| Window | 90 days at most, 30 by default | A longer window answers 400 VALIDATION_FAILED. |
| Query lists | 50 | Top queries and zero-result queries. |
| Search log retention | 90 days | Older searches are deleted. |
API keys
| Limit | Value | Meaning |
|---|---|---|
| Key name | 1 to 100 characters | |
| Index scope | 100 indices | Empty means every index of the project. |
| Allowed origins | 50 per public key |
Rate limits
Counted per minute. Past a limit the API answers 429 RATE_LIMITED with a Retry-After header. See Rate limits and errors for how to handle it.
| Route | Per key | Per client IP |
|---|---|---|
| Public search | 600 | 1200 |
| Public suggest | 1200 | 2400 |
/mcp | 600 | 1200 |
| Every other route, per secret key | 1200 | |
| Every other route, per signed-in user | 600 | |
| Sign in | 10 | |
| Register | 5 | |
| Forgot password | 5 | |
| Session refresh | 120 | |
| Email links (verify, reset) | 30 | |
| Resend verification mail | 3 per user |