API pagination

Vault uses pagination to improve performance when retrieving objects.

The default page size is specified in the PVAULT_SERVICE_DEFAULT_PAGE_SIZE environment variable. When you request a list of objects, you can use the page-size parameter to set a different page size. However, the page size cannot exceed the value specified in the PVAULT_SERVICE_MAX_PAGE_SIZE environment variable.

The response provides a results array containing the object details and a paging object with information about the page. For example:

{
  "results": [
    {
      "email": "mr.john@somemail.com"
    },
    {
      "email": "john1234@anotheremail.com"
    },
    …
  ],
  "paging": {
    "size": 100,
    "remaining_count": 901,
    "cursor": "AXfKgvXQNTZYiFCtBSTHbjkmYXiaE84oxgGzdeQyKXZbbG0sUX7jAwrUeaBIosUeXqYIKw=="
  }
}

In the paging object:

• size is the number of results returned.
• remaining_count is the number of items that remain to be returned in subsequent pages.
• By default, the remaining_count is 100,000 items even if there are more items that satisfy the query. When receiving a count of 100,000 items, you should not assume that there are exactly 100,000 items left, there may be more.
• Using the cursor, subsequent calls to paging eventually reach a remaining_count value of less than 100,000 items. Then, the figure is accurate.
• The remaining_count limit is configured by the PVAULT_SERVICE_MAX_PAGINATION_REMAINING_COUNT environment variable.
• cursor is a reference to the next page. You use the cursor in a follow-up call like this:

  GET api/pvlt/1.0/data/collections/employees/objects?reason=Analytics&props=email&cursor=AXfKgvXQNTZYiFCtBSTHbjkmYXiaE84oxgGzdeQyKXZbbG0sUX7jAwrUeaBIosUeXqYIKw==
  to obtain the next page.

The final page in a sequence of pages returns 0 for remaining_count and no cursor. For example:

{
  ...
  "paging": {
    "size": 1,
    "remaining_count": 0,
    "cursor": ""
  }
}