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

# Pagination

> Efficiently work with large datasets using cursor-based and offset pagination in the Givebutter API.

The Givebutter API uses pagination to break large result sets into manageable pages. This improves performance and allows you to retrieve data incrementally rather than loading thousands of records at once.

## Pagination Response Format

All paginated endpoints return responses in this structure:

<CodeGroup>
  ```json Response Structure theme={null}
  {
    "data": [
      // Array of resources (campaigns, transactions, contacts, etc.)
    ],
    "links": {
      "first": "https://api.givebutter.com/v1/campaigns?page=1",
      "last": "https://api.givebutter.com/v1/campaigns?page=5",
      "prev": "https://api.givebutter.com/v1/campaigns?page=1",
      "next": "https://api.givebutter.com/v1/campaigns?page=3"
    },
    "meta": {
      "current_page": 2,
      "from": 21,
      "last_page": 5,
      "path": "https://api.givebutter.com/v1/campaigns",
      "per_page": 20,
      "to": 40,
      "total": 95
    }
  }
  ```

  ```json First Page Example theme={null}
  {
    "data": [
      {
        "id": "camp_abc123",
        "title": "Annual Gala"
        // ... campaign data
      },
      {
        "id": "camp_def456",
        "title": "Spring Fundraiser"
        // ... campaign data
      }
      // ... 18 more campaigns
    ],
    "links": {
      "first": "https://api.givebutter.com/v1/campaigns?page=1",
      "last": "https://api.givebutter.com/v1/campaigns?page=5",
      "prev": null,
      "next": "https://api.givebutter.com/v1/campaigns?page=2"
    },
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 5,
      "path": "https://api.givebutter.com/v1/campaigns",
      "per_page": 20,
      "to": 20,
      "total": 95
    }
  }
  ```

  ```json Last Page Example theme={null}
  {
    "data": [
      {
        "id": "camp_xyz789",
        "title": "Year End Campaign"
        // ... campaign data
      }
      // ... only 15 campaigns on last page
    ],
    "links": {
      "first": "https://api.givebutter.com/v1/campaigns?page=1",
      "last": "https://api.givebutter.com/v1/campaigns?page=5",
      "prev": "https://api.givebutter.com/v1/campaigns?page=4",
      "next": null
    },
    "meta": {
      "current_page": 5,
      "from": 81,
      "last_page": 5,
      "path": "https://api.givebutter.com/v1/campaigns",
      "per_page": 20,
      "to": 95,
      "total": 95
    }
  }
  ```
</CodeGroup>

## Pagination Metadata

### Links Object

The `links` object provides ready-to-use URLs for navigating pages:

| Field   | Description                                         | Value When Not Available |
| ------- | --------------------------------------------------- | ------------------------ |
| `first` | URL to the first page of results                    | Never null               |
| `last`  | URL to the last page of results                     | Never null               |
| `prev`  | URL to the previous page (only if current page > 1) | `null` on first page     |
| `next`  | URL to the next page (only if more pages exist)     | `null` on last page      |

<Tip>
  The `next` link is the easiest way to paginate. Keep following `next` until it becomes `null` to
  fetch all results.
</Tip>

### Meta Object

The `meta` object provides detailed pagination state:

| Field          | Description                                      | Example                                   |
| -------------- | ------------------------------------------------ | ----------------------------------------- |
| `current_page` | The current page number (1-indexed)              | `2`                                       |
| `from`         | The index of the first item on this page         | `21`                                      |
| `to`           | The index of the last item on this page          | `40`                                      |
| `last_page`    | The total number of pages                        | `5`                                       |
| `per_page`     | Number of items per page                         | `20`                                      |
| `total`        | Total number of items across all pages           | `95`                                      |
| `path`         | Base URL for the resource (without query params) | `https://api.givebutter.com/v1/campaigns` |

## Query Parameters

Control pagination behavior with these query parameters:

| Parameter  | Description                             | Default | Max   |
| ---------- | --------------------------------------- | ------- | ----- |
| `page`     | The page number to retrieve (1-indexed) | `1`     | -     |
| `per_page` | Number of items per page                | `20`    | `100` |

<CodeGroup>
  ```bash Request Specific Page theme={null}
  curl "https://api.givebutter.com/v1/campaigns?page=3" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Custom Page Size theme={null}
  curl "https://api.givebutter.com/v1/campaigns?per_page=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Page 2 with 50 Items theme={null}
  curl "https://api.givebutter.com/v1/campaigns?page=2&per_page=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<Note>
  The maximum `per_page` value is **100**. Requesting more than 100 items per page will return an
  error.
</Note>