Pagination

All of the endpoints with a multi-record response within the Vista API support pagination. Pagination allows our services to provide the optimal experience for our customers. By implementing pagination in your application, you can minimize response times for requests and generally improve the end-user experience.

We use forward-only paging with a continuation token strategy. The API limits multi-record GET responses to 1,000 records, although the caller can provide a lower limit using the limit parameter.

Note: The API may return fewer records than the limit value. On rare occasions due to Cosmos database design, this may even be 0 records and a continuation token. Examination of the continuation token and next properties is needed to determine if additional records exist. As long as there is a next URL value, you should continue making GET calls to ensure all data is read..

Here's an example script that would return all the records, resetting continuation token to latest token after each response.

Make to use the continuation token exactly as provided and don't inadvertently introduce additional quotation marks or other changes in JSON handling, for example.

Fetch all employees example script

# Stop script execution if any command fails (equivalent to set -e)

$ErrorActionPreference = "Stop"

$ApiUrl = "https://api.xchange.trimble.com/connect/v1/direct/subscribers/12149/pr/2/data/employees/cache/search"
$AppKey = $env:PROD_APP_NETWORK_API_KEY


# Validate environment variable


if ([string]::IsNullOrEmpty($AppKey)) {
    Write-Error "Error: PROD_APP_NETWORK_API_KEY is not set."
    exit 1
}

$TotalRecords = 0
$RequestCount = 0
$ContinuationToken = $null

while ($true) {
    # Build payload object with filters removed
    $PayloadObj = [ordered]@{
        continuationToken = if ([string]::IsNullOrEmpty($ContinuationToken)) { $null } else { $ContinuationToken }
    }
    $Payload = $PayloadObj | ConvertTo-Json -Compress

    # Set up headers
    $Headers = @{
        "Content-Type"      = "application/json"
        "x-application-key" = $AppKey
    }

    try {
        # Send POST request and automatically parse JSON response
        $Response = Invoke-RestMethod -Uri $ApiUrl -Method Post -Headers $Headers -Body $Payload
    } catch {
        Write-Error "Error: Request #($RequestCount + 1) failed."
        Write-Error $_.Exception.Message
        exit 1
    }

    # Extract fields (fallback to 0 if count is missing)
    $Count = if ($null -ne $Response.count) { [int]$Response.count } else { 0 }
    $LatestToken = $Response.continuationToken

    $TotalRecords += $Count
    $RequestCount += 1

    # Log progress
    $TokenPresent = if (![string]::IsNullOrEmpty($LatestToken)) { "true" } else { "false" }
    Write-Host "Response #$RequestCount: count=$Count, running_total=$TotalRecords, continuation_token_present=$TokenPresent"

    # Break loop if no more pagination tokens are provided
    if ([string]::IsNullOrEmpty($LatestToken)) {
        break
    }

    $ContinuationToken = $LatestToken
}

Write-Host "Done. Total records returned: $TotalRecords"