Skip to main content

​
Overview

List endpoints support two pagination modes. Which one you get is decided by a single parameter: send cursor and you are in cursor mode, omit it and you stay in legacy page/limit mode. Cursor pagination is the recommended mode for anything that walks a full result set. It is stable under concurrent writes, and its cost does not grow as you move deeper into the results.
Legacy page/limit pagination is still fully supported and unchanged. No existing integration needs to be updated.

​
Endpoints that support cursor pagination

cursor, page, limit, sortBy, and sortOrder come from one shared pagination parameter set, so cursor is also listed on GET /file-type, GET /schemas/file-type, and GET /files/{fileId}/values. Those endpoints do not implement cursor mode yet: sending cursor there is accepted but ignored, and you still get the legacy page/limit response. Use page/limit on them.

​
Cursor pagination

Examples use the default base URL, https://api.orion.file.ai/prod/v1. If your workspace is on an instance-specific host, swap the hostname and change nothing else — see Switching between instances.
1

Request the first page

Send cursor with an empty value — the parameter’s presence is what selects cursor mode.
2

Read the pagination block

The response is wrapped in data plus a pagination object.
3

Follow nextCursor until hasMore is false

Pass the previous nextCursor value back as cursor. When hasMore is false, nextCursor is null and you have reached the end.
Cursor values are opaque and URL-encode them before use — they are base64 and can contain = characters.

​
Parameters

​
Pagination object

A cursor is bound to the sortBy, sortOrder, and filter values it was minted with. Changing any of them mid-walk invalidates the cursor and returns a 422. Start a new walk instead.

​
Legacy page/limit pagination

Omit cursor entirely and the response keeps its original shape: a named array (see the table above), plus count and currentPage.

​
Choosing a mode

Use cursor pagination

Walking a full result set, syncing to a warehouse, or paging through data that is being written to concurrently.

Use page/limit

You need a total count, jump-to-page behaviour, or you have an existing integration that already works.
Legacy mode gives you a total count; cursor mode does not — computing an exact total is what makes deep offset paging expensive. Use hasMore to drive your loop instead of a total.