# API Pagination (/docs/developer-resources/api-basics/api-pagination)

## 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
curl "https://api.monime.io/v1/payouts?limit=10&after=pyt-k6GMRZsCr61zfwCQtVemY2RrvQH" \
  -H "Authorization: Bearer $MONIME_ACCESS_TOKEN" \
  -H "Monime-Space-Id: $MONIME_SPACE_ID"
```

***

## Response Shape

Every paginated response includes a `pagination` object:

```jsonc
{
  "success": true,
  "messages": [],
  "result": [
    { "id": "pyt-k6GMRZsDq72agxDRuWfnZ3SswRJ" }, // the objects in this page,
    { "id": "pyt-k6GMRZsEt83bhyESvXgoA4TtxSK" }  // up to `limit` of them
  ],
  "pagination": {
    "count": 10, // how many objects this page holds
    "next": "cD0yMDI2LTA5LTMwVDEyOjMwOjAwWg" // pass as `after` for the next page; null on the last
  }
}
```

### 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. 

## 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.