Limits and behaviour
These are the limits and failure behaviours a developer or integrator should plan for. The table below applies to builds made after 2026-11-14; older builds may accept things these builds refuse.
| Area | Behaviour |
|---|---|
| Node size | A node holds at most 64 KiB in total: its transform, its name and all its properties. It also holds about 509 properties at most. A larger write is refused at write time. |
| Write budget | Node writes have a budget per author, per verse: a burst of 8 MiB, then 64 KiB per second. An over-budget write is answered HTTP 429 with the code write-budget-exceeded and a Retry-After header. |
| Node lists | Lists are paged. The response carries a next cursor; pages come in node-id order. |
| Queries | /query refuses a top-level LIMIT above 10,000. |
| Node history | A page holds 20 entries by default. A short page does not mean the end of the history: follow next_after_version until it is absent. |
| Scene hooks | A hook has a 250 ms deadline, up to 500 ms for a full-size input. A hook that does not answer in time refuses the write: HTTP 409 with hook-failed. A caller with too many hook calls in flight gets 503 with hook-busy. |
| External services | An extension calls external services only through hosts declared in its manifest. API keys are held by the app, never by the extension. |
Handling a refused write
A 429 write-budget-exceeded is safe to retry after the delay in Retry-After. Do not retry in a tight loop: the budget refills at 64 KiB per second, so a stream of large writes will keep being throttled. Batch property changes into fewer writes and keep nodes well under 64 KiB.
Hooks fail closed
If an extension serves a scene hook and does not answer within its deadline, the write it guards is refused rather than let through. Treat hook-failed as “the write did not happen”, and retry or surface it. A hook that is merely slow can therefore block writes to the scope it is bound to.
Paging
Never assume one page is everything. Node lists end when there is no next cursor, and node history ends when there is no next_after_version. A page that is shorter than the page size is not a signal either way.
Other limits worth knowing
These come from the project documentation and are not tied to that date.
- Export size.
/api/v1/queryreturns at most 10,000 rows or 8 MiB. Parquet and CSV exports return at most 500,000 rows or 128 MiB. Passing a cap is an error, never a silently truncated result. - Uploads. A single model upload over REST is capped at 256 MiB, and each owner has an upload quota of 2 GiB by default (
FE_API_UPLOAD_QUOTA_BYTES). - Local only. The desktop app’s API listens on
127.0.0.1and cannot be reached from other machines.