# Pagination



> Mailrith uses cursor pagination across list endpoints. This guide explains how to request the first page, continue with `next_cursor`, resume interrupted syncs, and reuse the same pattern across subscribers, tags, custom fields, forms, and segments.



- Human page: https://mailrith.com/developers/pagination

- Category: API Concepts

- Reading time: 6 min read



## What this guide covers

Page through large list endpoints safely with cursors, saved progress, and reusable sync loops.



## Use Cursor Pagination

Mailrith uses cursor pagination for list endpoints. Cursor pagination means each response tells you where to continue instead of asking you to guess a page number.

This matters when a workspace is changing while your integration is reading it. Subscribers, tags, forms, landing pages, and segments can be added while a sync is running. A cursor gives your integration a stable next step even when the total number of records changes.

Start without `starting_after` when you want the first page. If the response says `has_more` is true, copy `next_cursor` into the next request as `starting_after`. Continue until `has_more` is false.

1. Send the first list request with a `limit` and no `starting_after` value.
2. Process every item in the returned `data` array.
3. Read the `pagination` object.
4. If `has_more` is false, stop the loop.
5. If `has_more` is true, store `next_cursor` and send the next request with `starting_after=<next_cursor>`.
6. Write progress after each fully processed page so a scheduled sync can resume safely.
7. Use the same loop for subscribers, tags, custom fields, forms, landing pages, and segments.

- Use `limit` to choose how many records you want Mailrith to return at once.
- Use `starting_after` only after Mailrith has returned a `next_cursor` from the previous page.
- Do not invent cursor values, count pages, or assume that a record's database order will never change.
- For scheduled syncs, store the last cursor you successfully processed so a failed job can resume cleanly.
- For one-time exports or migrations, keep requesting pages until `has_more` is false.

**Paginated List Request**

```bash
curl "https://api.mailrith.com/v1/subscribers?limit=50&starting_after=subscriber_123" \
  -H "Authorization: Bearer mrk_example_secret_key"
```

**Paginated Response**

```json
{
  "data": [],
  "pagination": {
    "has_more": true,
    "next_cursor": "subscriber_456"
  }
}
```

## Apply the Same Pattern Across Resources

The same pagination pattern is used across list-style resources. Once your integration handles one list endpoint correctly, the same loop can usually be reused for other resources.

Keep the loop simple: send a request, process every item in `data`, save the next cursor, and stop only when Mailrith says there are no more results.

Avoid fetching an entire workspace into memory when a workspace may contain a large subscriber list. Process each page as it arrives, write your progress somewhere durable, and continue to the next cursor.

- Subscribers are usually the largest list and should always be processed page by page.
- Tags, custom fields, forms, landing pages, and segments may be smaller, but using the same cursor loop keeps the integration consistent.
- If your job is interrupted after processing a page, resume from the cursor after the last fully processed page.
- If you need a fresh full sync, start again without `starting_after` instead of reusing an old cursor from a different run.

Related OpenAPI operation groups:
- Subscribers
- Tags
- Custom Fields
- Forms
- Segments



## Related Guides

- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the core subscriber write surface in `v1`. This guide explains when to list, when to upsert, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests.

- [Tags API](https://mailrith.com/developers/tags.md): The tags surface gives integrations a lightweight way to manage subscriber labels. This guide explains when tags are the right choice, when custom fields are better, how to list or create tags, and how to name tags so real workspace users understand them.

- [Segments API](https://mailrith.com/developers/segments.md): The segments surface supports saved subscriber definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save them, and why preview is the safest step before using complex subscriber rules.