Limits and pagination
How big a result can be, how lists are paged, and how many requests you can make.
Results have a size limit. Lists come in pages. This page gives the numbers the server uses today.
The limits#
| Limit | Value |
|---|---|
| One tool result | 200 KiB |
read_file, one text read | 64 KiB (use offset and length to read on) |
read_file, one binary file | 256 KiB before base64 |
read_release with contents | 40 files per page |
search_products | 20 per page by default, at most 50 |
Lists (get_product, list_release_files, read_tokens) | at most 500 per page |
get_page and get_component | at most 200 files, 8 levels of imports |
| A cursor stays valid | 60 minutes |
| Requests | 60 per minute per account; 300 per minute when you only continue a cursor you were given |
Paging#
A tool that can return many items returns one page and a nextCursor.
- Read the page.
- If
nextCursoris notnull, call the same tool again withcursorset to it. - Repeat until
nextCursorisnull.
A cursor belongs to your account, to that exact request and to that release. If you change the inputs, the cursor is refused. After a new release is published, it answers release_replaced. Start the list again without a cursor.
Reading big files#
read_file reads text in ranges. Each result says where the next range starts in range.next. Pass it back as offset. A binary file is read whole: if it is too large, the answer is too_large and the next step is to download the ZIP from the product page.
Whole releases#
read_release with include_contents returns file contents a page at a time. For a large release, the CLI is faster: orvio pull sotto. See Pull into a project.
Rate limits#
Requests are counted per account each minute, as the table above shows. A request that only continues a cursor the server gave you draws on a larger budget. When you go over, the server answers HTTP 429 with a Retry-After header and the code rate_limited. Wait that many seconds and continue.
Good habits for agents#
- Ask for what you need: one page, one component, one set of tokens.
- Use
include_contents: falseto see what a page needs before reading it. - Page through lists; do not repeat the first call.