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:

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:

{
  "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.

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.