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

# Pagination

> Learn how to navigate through paginated responses from the Endor Labs REST API.

## About Pagination

When a response from the REST API includes many results, Endor Labs paginates the results and returns a subset of the results. For example, GET `/v1/namespaces/{tenant_meta.namespace}/findings` only returns 100 findings from the given namespace even if the namespace has more than 100 findings. This makes the response easier to handle for servers and for people.

You can use the additional data from the list response to request additional pages of data.

This article explains how to request additional pages of results for paginated responses and how to change the number of results returned on each page.

## Fetch all resources with `--list-all`

The `endorctl` CLI provides the `--list-all` flag that allows you to fetch all results. Internally, `endorctl` handles the pagination through multiple requests.

```bash theme={null}
endorctl api list --resource Finding --list-all
```

## Using `page_size`

The `page_size` field allows you to control the number of elements returned. By default, this value is 100, with a maximum of 500. The higher this value is, the longer it may take to get a result.

<Tabs>
  <Tab title="endorctl">
    ```bash theme={null}
    endorctl api list --resource Finding \
      --page-size=50
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    curl --get \
      --header "Authorization: Bearer $ENDOR_TOKEN" \
      --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.page_size=50"
    ```
  </Tab>
</Tabs>

## Iterating through results

You can iterate through results using the `page_id` or `page_token` fields.

### Using `page_id`

When a response spans multiple pages, it includes a `next_page_id` value. Use this value to fetch additional pages of results.

For example, the response to the above request contains the first 50 elements in the `objects` field along with the following values in the `response` field:

```json theme={null}
{
  "list": {
    "objects": [
        ...
    ],
    "response": {
      "next_page_id": "633dd86976186a89d64628c1",
      "next_page_token": 50
    }
  }
}
```

To access the next page of results, you can use the `next_page_id` value as the value of `page_id` in the next request. For example:

<Tabs>
  <Tab title="endorctl">
    ```bash theme={null}
    endorctl api list --resource Finding \
      --page-size=50 \
      --page-id=633dd86976186a89d64628c1
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    curl --get \
      --header "Authorization: Bearer $ENDOR_TOKEN" \
      --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.page_size=50&list_parameters.page_id=633dd86976186a89d64628c1"
    ```
  </Tab>
</Tabs>

This returns the next 50 elements, starting after the last element of the previous page.

### Using `page_token`

`page_token` and `next_page_token` provide the same pagination capability as `page_id` and `next_page_id`, using a numeric offset instead of a cursor. However, we recommend using `page_id` and `next_page_id` as they offer better performance for the request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.