Pagination

List endpoints return results a page at a time. Most support two modes, chosen by one parameter: send cursor and you get cursor mode; leave it out and you get legacy page/limit mode. Use cursor mode for anything that walks a whole result set — it stays correct while data changes and costs the same on page 500 as on page 1. Legacy mode is still fully supported. Existing integrations don’t need to change.

When to use it

Use cursor mode when you…	Use legacy mode when you…
Walk a full result set or sync to a warehouse	Need a total `count`
Page through data that is being written to	Need to jump to a specific page
Want a stable order without extra parameters	Already have a working integration

Cursor mode has no total count — counting is what makes deep offset paging expensive. Drive your loop with hasMore.

How it works

Endpoints

Endpoint	Cursor mode	Legacy mode	Legacy response key
`GET /v1/files`	Yes	Yes	`files`
`GET /v1/schemas`	Yes	Yes	`schemas`
`GET /v1/directories`	Yes — `data` is a flat list with no `subfolders` nesting	Yes	`directories`
`GET /v1/agent/sessions`	Only mode	No	—
`GET /v1/agent/sessions/{session_id}/messages`	Only mode	No	—

cursor is also listed on GET /v1/file-type, GET /v1/schemas/file-type and GET /v1/files/{fileId}/values, because they share the same parameter set. Those endpoints don’t implement cursor mode: cursor is accepted and ignored, and you get a legacy response. Use page and limit there.

Cursor mode

Request the first page

Send cursor with an empty value. Its presence is what switches on cursor mode. (FILEAI_BASE_URL is https://api.orion.file.ai/prod/v1, or your regional host.)

curl "$FILEAI_BASE_URL/files?cursor=&limit=50" \
  -H "x-api-key: $FILEAI_API_KEY"

On the agent session and message lists, which only have cursor mode, you can simply omit cursor for the first page.

Read the pagination object

Results come back in data, with a pagination object:

{
  "data": [{ "fileId": "b765bd00-181e-4737-b4d9-004dadd6bd45" }],
  "pagination": {
    "limit": 50,
    "nextCursor": "<nextCursor>",
    "hasMore": true
  }
}

Follow nextCursor until hasMore is false

Pass nextCursor back as cursor, with the same filters and sort. When hasMore is false, nextCursor is null and you’re done.

curl "$FILEAI_BASE_URL/files?cursor=<nextCursor>&limit=50" \
  -H "x-api-key: $FILEAI_API_KEY"

Cursors are opaque, signed strings in unpadded base64url, so they are already safe to put in a URL. Don’t build, decode or edit them. A cursor only works with the request that produced it. It is bound to:

the endpoint and your workspace,
sortBy and sortOrder,
every filter on the request (for example updatedAfter, directoryId, fileIds).

Change any of these mid-walk, or send a cursor that has been altered, and you get 400 BAD_REQUEST (“Please restart pagination”). Start a new walk without a cursor.

Sorting by updatedAt is best-effort: a row updated during your walk can move past the point you’ve reached and appear again, or be skipped until your next walk. createdAt and _id give an exact walk.

Legacy mode

Leave cursor out and the response keeps its original shape: a named array, plus count and currentPage.

curl "$FILEAI_BASE_URL/files?page=1&limit=100&sortBy=createdAt&sortOrder=ASC" \
  -H "x-api-key: $FILEAI_API_KEY"

{
  "files": [{ "fileId": "b765bd00-181e-4737-b4d9-004dadd6bd45" }],
  "count": 1350,
  "currentPage": 1
}

In legacy mode on GET /v1/files and GET /v1/schemas, results are only sorted when you send both sortBy and sortOrder. If either is missing, the order is unspecified and pages can overlap or skip rows. Always send both.

Reference

Cursor mode parameters

Parameter	Default	Description
`cursor`	—	Empty for the first page, then the previous `nextCursor`. Presence selects cursor mode.
`limit`	50	Page size. A value above 100 is reduced to 100. Zero, negative or repeated values are a `400`.
`sortBy`	`createdAt`	`createdAt`, `updatedAt` or `_id`. Anything else is a `400`.
`sortOrder`	`ASC`	`ASC` or `DESC`.

The agent lists take only cursor and limit, with their own order and sizes:

Endpoint	Order	Default `limit`	Maximum
`GET /v1/agent/sessions`	Newest first	50	100
`GET /v1/agent/sessions/{session_id}/messages`	Oldest first	20	50

Pagination object

Field	Type	Description
`limit`	number	Page size actually applied.
`nextCursor`	string \| null	Cursor for the next page; `null` when `hasMore` is `false`.
`hasMore`	boolean	Whether more results exist after this page.

Legacy mode parameters

Parameter	Default	Description
`page`	1	Page number.
`limit`	100	Items per page. There is no maximum; a zero, negative or non-numeric value falls back to 100.
`sortBy`	—	Field to sort by. Only applied together with `sortOrder`.
`sortOrder`	—	`ASC` or `DESC`. Only applied together with `sortBy`.

Incremental loading

Combine cursors with updatedAfter to sync changes.

Agent sessions

Cursor-only lists of sessions and messages.

Errors

What a 400 for a bad cursor looks like.

Authentication and regions

Base URLs and request conventions.

Get started

Products

Build

Go live

When to use it

How it works

Endpoints

Cursor mode

Legacy mode

Reference

Cursor mode parameters

Legacy mode parameters

Incremental loading

Agent sessions

Errors

Authentication and regions

​When to use it

​How it works

​Endpoints

​Cursor mode

​Legacy mode

​Reference

​Cursor mode parameters

​Pagination object

​Legacy mode parameters

​Related

Incremental loading

Agent sessions

Errors

Authentication and regions

When to use it

How it works

Endpoints

Cursor mode

Legacy mode

Reference

Cursor mode parameters

Pagination object

Legacy mode parameters

Related