> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> The list response shape, query parameters, and how to page reliably.

List endpoints return a consistent page object inside the standard success envelope.

## Shape

```json theme={null}
{
  "status": 200,
  "message": "Files retrieved successfully",
  "data": {
    "total": 132,
    "page": 1,
    "totalPages": 7,
    "limit": 20,
    "data": []
  }
}
```

| Field | Meaning |
| - | - |
| `total` | Total matching items across all pages |
| `page` | Current page, 1-based |
| `totalPages` | Total number of pages |
| `limit` | Page size used for this response |
| `data` | The items on this page |

Note the nesting: the envelope has `data`, and the page object also has `data`. Be deliberate when decoding.

## Query parameters

| Parameter | Applies to | Notes |
| - | - | - |
| `page` | File and folder lists | 1-based |
| `limit` | File and folder lists | Page size |
| `searchTerm` | File and folder lists, folder content | Free-text filter |
| `orderBy` | File and folder lists | Sort field |
| `sortBy` | Folder content | Sort field |
| `sortOrder` | Folder content | Sort direction |

Defaults and accepted ranges are enforced by the backend. If you omit them, do not assume a specific page size; read `limit` from the response.

## Folder content is special

`GET /folders/{folderId}/content` returns a different object:

```json theme={null}
{
  "folderId": "…",
  "folderName": "Contracts",
  "totalItems": 42,
  "totalFiles": 30,
  "totalFolders": 12,
  "page": 1,
  "limit": 20,
  "totalPages": 3,
  "content": []
}
```

Key differences:

* items are under `content`, not `data`,
* subfolders are returned **before** files within the ordered result,
* `totalItems` equals `totalFiles + totalFolders`.

## Subfolders are not paginated

`GET /folders/{folderId}/subfolders` returns the full list plus a parent descriptor:

```json theme={null}
{
  "data": [],
  "total": 12,
  "parentFolder": {
    "id": "…",
    "name": "Contracts",
    "bucketId": "…"
  }
}
```

For deep trees, this can be a large response. Prefer folder content when you need pagination.

## File lists

`GET /files/findAll/{bucketId}` returns the standard page object for one bucket.

Deleted files have their own bucket-scoped listing: `GET /files/deleted-files/{bucketId}`.

## Paging strategy

1. Start at `page=1` and read `totalPages`.
2. Prefer small pages for interactive UI, larger pages for batch jobs.
3. Do not rely on a stable order unless you pass `orderBy` or `sortBy`. Items can move between pages if the underlying set changes while you page.
4. For full exports, take a snapshot by filtering on a time range where possible, rather than paging a live-changing set.
5. Stop when `page >= totalPages`, not when a page is empty.

## Consistency caveat

Pagination over a live set is not a transaction. If items are created or deleted during a scan:

* you may see an item twice,
* you may miss an item,
* `total` may change between pages.

Make your reconciliation idempotent. Key on `fileId` and `folderId`, not on position.

## Related

> **[Conventions](https://docs.everabyte.com/api-reference/conventions.md)**
>
> Envelopes and identifiers.

> **[Files overview](https://docs.everabyte.com/api-reference/files/overview.md)**
>
> File listing operations.

> **[Folders overview](https://docs.everabyte.com/api-reference/folders/overview.md)**
>
> Folder browsing operations.

> **[Errors](https://docs.everabyte.com/api-reference/errors.md)**
>
> Failure handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.