Pagination

Navigate large result sets with the Provisionr Workspace API

List endpoints that return large datasets use page-based pagination. Paginated responses include metadata to help you navigate through result sets.

Making Paginated Requests

Use the page query parameter to request a specific page of results.

curl https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users?page=2 \
  -H "Authorization: Bearer prv-your-token"

Response Structure

Paginated responses wrap the resource data in an envelope with navigation metadata.

{
    "current_page": 2,
    "data": [
        { "..." : "..." }
    ],
    "first_page_url": "https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users?page=1",
    "from": 16,
    "last_page": 5,
    "last_page_url": "https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users?page=5",
    "links": [
        { "url": "https://...?page=1", "label": "« Previous", "active": false },
        { "url": "https://...?page=1", "label": "1", "active": false },
        { "url": null, "label": "2", "active": true },
        { "url": "https://...?page=3", "label": "3", "active": false },
        { "url": "https://...?page=3", "label": "Next »", "active": false }
    ],
    "next_page_url": "https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users?page=3",
    "path": "https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users",
    "per_page": 15,
    "prev_page_url": "https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users?page=1",
    "to": 30,
    "total": 74
}

Response Fields

Field	Type	Description
current_page	integer	The current page number
data	array	The resource items for this page
first_page_url	string | null	URL to the first page
from	integer | null	Index of the first item on this page
last_page	integer	Total number of pages
last_page_url	string | null	URL to the last page
links	array	Navigation link objects
next_page_url	string | null	URL to the next page, null if on last page
path	string | null	Base path for the endpoint
per_page	integer	Number of items per page
prev_page_url	string | null	URL to the previous page, null if on first page
to	integer | null	Index of the last item on this page
total	integer	Total number of items across all pages

Iterating Through Pages

To iterate through all pages, continue making requests until next_page_url is null.

import requests

url = "https://wks-a1b2c3d4.provisionr.io/api/v1/directory/users"
headers = {"Authorization": "Bearer prv-your-token"}

while url:
    response = requests.get(url, headers=headers).json()

    for item in response["data"]:
        # Process each item
        pass

    url = response["next_page_url"]

Not all list endpoints return paginated responses. Some endpoints return a plain array of results. Check the endpoint documentation to confirm the response format.