---
title: Pagination
description: Handle paginated list responses from the Reloop API.
---
> For the complete documentation index, see [llms-docs.txt](/llms-docs.txt) or the site index [llms.txt](/llms.txt). Full docs corpus: [llms-full-docs.txt](/llms-full-docs.txt). Prefer markdown URLs (append `.md`) for agent consumption. Product skill: [skill.md](/skill.md).


All list endpoints in the Reloop API use **offset-based pagination**. You control the page size and page number using query parameters, and the response includes metadata so you can calculate total pages and build navigation.

## Query Parameters

| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| `page` | `number` | `1` | — | The page number to retrieve (1-indexed). |
| `limit` | `number` | `20` | `100` | The number of records to return per page. |

**Example request:**

```bash
curl "https://reloop.sh/api/contacts/v1/list?page=2&limit=50" \
  -H "x-api-key: rl_prod_YOUR_API_KEY"
```

## Response Structure

Pagination metadata is returned at the **root** of the JSON response alongside the data array. The exact field names vary by endpoint, but every paginated response includes `total`, `page`, and `limit`.

### Contacts

The contacts list endpoint includes additional aggregate counts:

```json
{
  "object": "contact",
  "contacts": [...],
  "total": 120,
  "page": 1,
  "limit": 20,
  "totalContacts": 120,
  "subscribedContacts": 100,
  "unsubscribedContacts": 20,
  "event": "contact.list"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `contacts` | `array` | The list of contact objects for the current page. |
| `total` | `number` | Total number of contacts matching the query. |
| `page` | `number` | The current page number. |
| `limit` | `number` | The page size used for this request. |
| `totalContacts` | `number` | Total contacts in the organization. |
| `subscribedContacts` | `number` | Number of contacts with an active subscription. |
| `unsubscribedContacts` | `number` | Number of contacts who have unsubscribed. |

### Templates

```json
{
  "templates": [...],
  "total": 45,
  "page": 1,
  "limit": 20,
  "event": "template.list"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `templates` | `array` | The list of template objects for the current page. |
| `total` | `number` | Total number of templates matching the query. |
| `page` | `number` | The current page number. |
| `limit` | `number` | The page size used for this request. |

## Calculating Total Pages

Use the `total` and `limit` fields to calculate the number of pages:

```javascript
const totalPages = Math.ceil(response.total / response.limit);
const hasNextPage = response.page < totalPages;
```