---
title: "Queries — Pagination"
aliases: [payload-pagination, payload-find-pagination]
tags: [payloadcms, queries, pagination, rest-api, local-api]
sources: [raw/queries__pagination.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

All Payload `find` operations are **paginated by default**. Responses wrap documents in a `docs` array alongside pagination metadata.

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `limit` | `10` | Max documents returned per page |
| `page` | `1` | Which page to fetch |
| `pagination` | `true` | Set `false` to disable and return all docs |

> `limit: 0` automatically disables pagination (same as `pagination: false`).

## Local API

```ts
const posts = await payload.find({
  collection: 'posts',
  limit: 10,
  page: 2,
})
```

## REST API

```
GET /api/posts?limit=10&page=2
```

## Response Shape

```json
{
  "docs": [...],
  "totalDocs": 6,
  "limit": 10,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}
```

| Field | Description |
|-------|-------------|
| `docs` | Array of documents for the current page |
| `totalDocs` | Total documents in the collection matching the query |
| `totalPages` | Total pages at the current `limit` |
| `pagingCounter` | Index of the first doc on this page |
| `hasPrevPage` / `hasNextPage` | Boolean navigation flags |
| `prevPage` / `nextPage` | Page numbers or `null` |

## Performance Tips

### Limit to 1 when querying by unique field

```ts
await payload.find({
  collection: 'posts',
  where: { slug: { equals: 'my-post' } },
  limit: 1,   // no need to scan further
})
```

### Disable pagination for bulk operations

```ts
const all = await payload.find({
  collection: 'posts',
  pagination: false,  // skips COUNT query overhead
})
```

Disabling pagination removes the `COUNT(*)` overhead — useful for migrations, exports, or scheduled jobs processing all documents.

## Key Takeaways

- All `find` queries return paginated results by default (`limit: 10`, `page: 1`)
- Response always has `docs[]` + metadata fields (`totalDocs`, `totalPages`, `hasNextPage`, etc.)
- Set `limit: 1` when querying by unique field (slug, email) for a fast DB lookup
- Set `pagination: false` (or `limit: 0`) to retrieve all documents in one call — avoids COUNT overhead
- Works identically across Local API, REST, and GraphQL (GraphQL has its own pagination shape)

## Related

- [[wiki/payloadcms/queries|Queries — Overview]] — where operators, sort, select, depth
- [[wiki/payloadcms/queries-depth|Queries — Depth]] — relationship population depth
- [[wiki/payloadcms/rest-api|REST API]] — full query param reference
- [[wiki/payloadcms/local-api|Local API]] — direct DB access patterns
