> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/guides/paginating-api-results.md).

# Paginating API results

List, filter, and related-entity endpoints return paginated results using cursor-based pagination. Instead of page numbers, you use the ID of the last item from the previous page to fetch the next page.

## How It Works

{% stepper %}
{% step %}
Make your first request with a `cursor_configuration.size` to control how many results you get back.
{% endstep %}

{% step %}
The response contains an `items` array with your results.
{% endstep %}

{% step %}
To get the next page, take the ID of the **last item** in the response and pass it as `cursor_configuration.after_id` in your next request.
{% endstep %}

{% step %}
Repeat until you receive fewer items than your requested `size`, which indicates you've reached the last page.
{% endstep %}
{% endstepper %}

## Pagination Parameters

Pass these in the JSON request body:

| Field                           | Type    | Default | Description                                                                   |
| ------------------------------- | ------- | ------- | ----------------------------------------------------------------------------- |
| `cursor_configuration.size`     | integer | 50      | How many results to return per page.                                          |
| `cursor_configuration.after_id` | string  | —       | The ID of the last item from the previous page. Omit this for the first page. |

## Sorting

The sort field name varies depending on the endpoint type:

| Endpoint Type                      | Sort Field       | Default  | Values              |
| ---------------------------------- | ---------------- | -------- | ------------------- |
| **List** and **Related** endpoints | `sorting_type`   | `"desc"` | `"asc"` or `"desc"` |
| **Filter** endpoints               | `sort_direction` | `"desc"` | `"asc"` or `"desc"` |

## Example: First Page

```bash
curl -X POST https://your-domain/v1/people/list \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cursor_configuration": {
      "size": 10
    },
    "sorting_type": "asc"
  }'
```

**Response:**

```json
{
  "status": "Success",
  "data": {
    "items": [
      { "id": "aaa-111", "external_id": "user-001", "first_name": "Alice" },
      { "id": "bbb-222", "external_id": "user-002", "first_name": "Bob" },
      "... (8 more items)"
    ]
  }
}
```

## Example: Next Page

Use the last item's ID as `after_id`:

```bash
curl -X POST https://your-domain/v1/people/list \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cursor_configuration": {
      "size": 10,
      "after_id": "bbb-222"
    },
    "sorting_type": "asc"
  }'
```

## Tips

* If you don't pass `cursor_configuration` at all, the API defaults to returning 50 results in descending order.
* An empty `items` array or fewer items than the requested `size` means there are no more pages.
* The ID you pass as `after_id` depends on the entity type: for people it's the `id` (UUID), for records it's the `record_id` (MongoDB ObjectID).