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

# API Pagination

> How to page through Monime resources efficiently using cursors.

# Overview

Monime uses **cursor-based pagination** for list endpoints. Every `listing` Responses include a `pagination` object with a cursor you pass back to fetch the next page.
This design is stable, efficient, and avoids the pitfalls of offset-based paging under changing datasets.

***

## Request Shape

Pagination on Monime APIs is controlled with **query parameters**:

* **`limit`** → how many objects to return in one page.
* **`after`** → an opaque cursor (usually the `id` of the last object from the previous page).

This allows you to step through results page by page in a consistent order.

Example request:

```bash theme={null}
curl "https://api.monime.io/v1/payouts?limit=10&after=pyt-k6GMRZsCr61zfwCQtVemY2RrvQH" \
  -H "Authorization: Bearer mon_***"
```

***

## Response Shape

Every paginated response includes a `pagination` object:

```json theme={null}
{
  "success": true,
  "messages": [],
  "result": [
   {}, // Item 1
   {}, // Item 2
   ....
  ],
  "pagination": {
    "count": <num-of-object-in-page>,
    "next": "<next-page-cursor>"
  }
}
```

### When to Stop Paging

* If `pagination.next` is present → there are more results. Pass this value as `after` in your next request.

* If `pagination.next` is `null` or absent → you’ve reached the end of the collection. Stop paging.

<Info> A smaller `count` than your requested `limit` often indicates you’re on the final page, but the definitive signal
is when `next` is `null` or missing. </Info>

## Best Practices for Paging

### Choose sane page sizes

* Start with `limit=30–50` for bulk jobs; use smaller limits for interactive UIs.
* Larger pages → fewer round trips; balance with payload size and client memory.

### Always drive from the cursor

* Read `pagination.next` and pass it back as `after` in the next call.
* Don’t fabricate or modify cursors; they are opaque and query-specific.
* Stop when `pagination.next` is `null`/ absent.

### Keep filters stable while paging

* Apply all filterss before paging.
* Changing filters mid-stream invalidates the cursor and can skip/duplicate items.

### Checkpoint for resumability

* Persist `{endpoint, filters}` after each page.
* On restart, resume with the last `after`. For strict windows, bound by timestamp.

### Be nice to rate limits

* Pace requests: small delay (50–200ms) between pages for steady flows.
* On `429`, honor `Retry-After`; then continue from the **same** cursor.
* Remember endpoint caps (live: **20 req/s**, test: **5 req/s**) and token/space quotas.

### Avoid N+1 request patterns

* Prefer list responses that already include fields you need.
* If you must hydrate per-item, batch those lookups and rate-gate them.

### Control parallelism

* Cap concurrency per token and per endpoint; add jitter to avoid synchronized bursts.