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

# Pagination

Some API requests will retrieve a large dataset. To ensure proper handling of this data, EmailBison will paginate the response.

This essentially means that you will receive chunks, or pages, of the data.
The response will be broken up into pages of 15 data entries per page, with information on how to view the next chunk.

For example, a `GET` request at the endpoint `/api/leads` will always be paginated, as there could be thousands of entries in leads.

Paginated responses from the API will have a `data` field for the entries at this page, as well as `links` and `meta` fields that provide you with information about the pagination in the response.

<Accordion title="Show example of a paginated response from the leads endpoint">
  ```json 200 {17-28} theme={null}
  {
      "data": [
          {
              "id": 835910,
              "first_name": "John",
              "last_name": "Doe",
              "email": "JohnDoe@email.com",
          },
          {
              "id": 835898,
              "first_name": "Jane",
              "last_name": "Doe",
              "email": "JaneDoe@email.com",
          },
  		... +13 Leads
      ],
      "links": {
          "first": "https://dedi.emailbison.com/api/leads?page=1",
          "last": "https://dedi.emailbison.com/api/leads?page=4",
          "prev": null,
          "next": "https://dedi.emailbison.com/api/leads?page=2"
      },
  	"meta": {
          "current_page": 1,
          "from": 1,
          "last_page": 4,
  		...Extra information truncated
  	}
  }
  ```
</Accordion>

## Retrieving the data programmatically

Send a request to your desired paginated endpoint.

After processing the data received, you would then send a request to the endpoint provided at `links.next` in the response, if it is **not** `null`.

Alternatively, you could loop the query by adding the page number as a paremeter for your request, incrementing the page number until you reach `meta.last_page`.

This looks like `YOUR_URL.com/api/leads?page={page_number}`, where `{page_number}` is incremented by 1 each time until you reach `meta.last_page`.

## Retrieving a specific page

Add a query paramter to the end of your request with the page number.

This looks like `YOUR_URL.com/api/leads?page={page_number}`, where `{page_number}` is the page you would like to retrieve.

## Cursor Pagination vs Default Page Pagination

The main difference between the two is that `cursor` pagination lets you traverse data much faster than the traditional page based pagination.

If you or your team is requesting large amounts of data to loop through, we recommend using cursor pagination.

<Warning>Traditional page based pagination is automatically limited to 1000 pages for all `index` routes (eg `/api/leads`, `/api/replies`, etc.). For larger datasets, use cursor pagination.</Warning>

#### How does cursor pagination work?

When using cursor pagination, pass in an extra query parameter called `pagination_type` set to `cursor`.

This will instruct the API to return the response with values for the `next_cursor` and `prev_cursor`.

Think of a cursor as a "pointer," where each dataset belongs to a cursor. To request the next page, your request will need to contain that page's cursor.

#### Example

Request the first page of leads and set `pagination_type` to `cursor`:

`YOUR_URL.com/api/leads?pagination_type=cursor`

You'll get your list of leads along with the following `meta` info:

```json theme={null}
"meta": {
    "path": "https://dedi.emailbison.com/api/leads",
    "per_page": 15,
    "next_cursor": "eyJpZCI6NzQ1NjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null
}
```

To request the next page, pass the `next_cursor` value as the `cursor` query parameter:

`YOUR_URL.com/api/leads?pagination_type=cursor&cursor=eyJpZCI6NzQ1NjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0`

That page will then return a `meta` object containing cursors for both the previous and next page:

```json theme={null}
"meta": {
    "path": "https://dedi.emailbison.com/api/leads",
    "per_page": 15,
    "next_cursor": "eyJpZCI6NzQ1NDUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": "eyJpZCI6NzQ1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9"
}
```

Continue using the `next_cursor` value from each response as the `cursor` query parameter on your next request to traverse the full dataset.