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

# Pagination

> Learn how to paginate through large result sets using limit/offset or cursor-based pagination.

All Mavio API list endpoints return paginated results. The API supports two pagination strategies depending on the endpoint: **limit/offset** (most endpoints) and **cursor-based** (real-time feeds).

## Limit/offset pagination

Most list endpoints accept `limit` and `offset` query parameters. This approach is best for browsing through results where you need random page access.

| Parameter | Type    | Default | Description                                           |
| --------- | ------- | ------- | ----------------------------------------------------- |
| `limit`   | integer | 20      | Number of items to return. Must be between 1 and 100. |
| `offset`  | integer | 0       | Number of items to skip before returning results.     |

Every paginated response includes a `pagination` object:

```json theme={null}
{
  "data": [ ... ],
  "pagination": {
    "total": 142,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

| Field      | Type    | Description                                        |
| ---------- | ------- | -------------------------------------------------- |
| `total`    | integer | Total number of items matching your filters.       |
| `limit`    | integer | The limit value used in this request.              |
| `offset`   | integer | The offset value used in this request.             |
| `has_more` | boolean | `true` if there are more results beyond this page. |

### Paginating through all results

To retrieve all results, increment `offset` by `limit` until `has_more` is `false`.

<CodeGroup>
  ```python Python theme={null}
  import mavio

  client = mavio.Client(api_key="mvo_live_abc123")

  all_meetings = []
  offset = 0
  limit = 50

  while True:
      response = client.meetings.list(limit=limit, offset=offset)
      all_meetings.extend(response.data)
      if not response.pagination.has_more:
          break
      offset += limit

  print(f"Fetched {len(all_meetings)} meetings")
  ```

  ```javascript Node.js theme={null}
  import Mavio from '@mavio/sdk';

  const client = new Mavio({ apiKey: 'mvo_live_abc123' });

  const allMeetings = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const { data, pagination } = await client.meetings.list({ limit, offset });
    allMeetings.push(...data);
    if (!pagination.has_more) break;
    offset += limit;
  }

  console.log(`Fetched ${allMeetings.length} meetings`);
  ```

  ```bash cURL theme={null}
  # Page 1
  curl -G https://api.mavioapp.com/v1/meetings \
    -H "Authorization: Bearer mvo_live_abc123" \
    -d limit=50 \
    -d offset=0

  # Page 2
  curl -G https://api.mavioapp.com/v1/meetings \
    -H "Authorization: Bearer mvo_live_abc123" \
    -d limit=50 \
    -d offset=50

  # Continue until has_more is false
  ```
</CodeGroup>

## Cursor-based pagination

Some real-time endpoints (such as webhook event logs) use cursor-based pagination for consistent results when new items are being created.

| Parameter | Type    | Description                                                        |
| --------- | ------- | ------------------------------------------------------------------ |
| `limit`   | integer | Number of items to return (1-100, default 20).                     |
| `cursor`  | string  | Opaque cursor from the previous response. Omit for the first page. |

```json theme={null}
{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImV2dF8xMjM0NTY3ODkwIn0=",
    "has_more": true
  }
}
```

Pass `next_cursor` as the `cursor` parameter in your next request to fetch the following page.

## Best practices

<AccordionGroup>
  <Accordion title="Use reasonable page sizes">
    A `limit` of 20-50 is optimal for most use cases. Requesting 100 items per page increases response time and payload size.
  </Accordion>

  <Accordion title="Cache total counts">
    The `total` field requires a count query on each request. If you only need to check for more results, use `has_more` instead of comparing `offset + limit < total`.
  </Accordion>

  <Accordion title="Handle concurrent modifications">
    With limit/offset pagination, items may shift between pages if new records are created or deleted between requests. For consistency-critical workflows, prefer cursor-based endpoints or filter by a fixed date range.
  </Accordion>

  <Accordion title="Respect rate limits">
    Paginating through large datasets generates many requests. Add a small delay between pages or use a larger `limit` to stay within [rate limits](/api-reference/rate-limits).
  </Accordion>
</AccordionGroup>