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

# Pagination

> How to paginate through list endpoints in the Encrata API.

## Overview

List endpoints that return multiple items support pagination using `limit` and `offset` query parameters.

## Parameters

| Parameter | Type    | Default | Max | Description               |
| --------- | ------- | ------- | --- | ------------------------- |
| `limit`   | integer | 20      | 100 | Number of items to return |
| `offset`  | integer | 0       | —   | Number of items to skip   |

<Note>
  Contact list endpoints currently return all items without pagination.
</Note>

## Response format

Paginated responses include a `total` field alongside the data array:

```json theme={"dark"}
{
  "runs": [
    {
      "id": "run_abc123",
      "monitor_id": "mon_xyz",
      "status": "completed",
      "created_at": "2026-05-18T10:00:00Z"
    }
  ],
  "total": 47
}
```

## Paginated endpoints

| Endpoint                                            | Array field | Default limit | Max limit |
| --------------------------------------------------- | ----------- | ------------- | --------- |
| `GET /api/agent/monitors/{id}/runs`                 | `runs`      | 20            | 100       |
| `GET /api/agent/monitors/{id}/runs/{runId}/results` | `results`   | 20            | 100       |
| `GET /api/agent/monitoring/runs`                    | `runs`      | 20            | 100       |
| `GET /api/agent/monitoring/results`                 | `results`   | 20            | 100       |

## Example

Fetch the second page of monitor runs (items 21–40):

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl "https://encrata.com/api/agent/monitors/mon_xyz/runs?limit=20&offset=20" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.get(
      "https://encrata.com/api/agent/monitors/mon_xyz/runs",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"limit": 20, "offset": 20},
  )
  data = resp.json()
  print(f"Showing {len(data['runs'])} of {data['total']} runs")
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch(
    "https://encrata.com/api/agent/monitors/mon_xyz/runs?limit=20&offset=20",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await resp.json();
  console.log(`Showing ${data.runs.length} of ${data.total} runs`);
  ```
</CodeGroup>

## Iterating through all pages

<CodeGroup>
  ```python Python theme={"dark"}
  def get_all_runs(monitor_id, api_key):
      runs = []
      offset = 0
      limit = 100

      while True:
          resp = requests.get(
              f"https://encrata.com/api/agent/monitors/{monitor_id}/runs",
              headers={"Authorization": f"Bearer {api_key}"},
              params={"limit": limit, "offset": offset},
          )
          data = resp.json()
          runs.extend(data["runs"])

          if offset + limit >= data["total"]:
              break
          offset += limit

      return runs
  ```

  ```javascript JavaScript theme={"dark"}
  async function getAllRuns(monitorId, apiKey) {
    const runs = [];
    let offset = 0;
    const limit = 100;

    while (true) {
      const resp = await fetch(
        `https://encrata.com/api/agent/monitors/${monitorId}/runs?limit=${limit}&offset=${offset}`,
        { headers: { Authorization: `Bearer ${apiKey}` } }
      );
      const data = await resp.json();
      runs.push(...data.runs);

      if (offset + limit >= data.total) break;
      offset += limit;
    }

    return runs;
  }
  ```
</CodeGroup>

## Filtering

Some endpoints support additional query filters alongside pagination:

| Parameter      | Endpoints                                   | Description                                            |
| -------------- | ------------------------------------------- | ------------------------------------------------------ |
| `type`         | `/monitoring/runs`, `/monitoring/results`   | Filter by monitor type (`email`, `domain`, `ip`, etc.) |
| `changes_only` | `/runs/{id}/results`, `/monitoring/results` | Only return items with detected changes                |