Pagination

Overview

Many Falcon API endpoints return paginated results to handle large datasets efficiently. PSFalcon provides automatic pagination support through the -All parameter, allowing you to retrieve complete result sets without manual page handling.

How Pagination Works

From /home/daytona/workspace/source/private/Private.ps1:619-661, PSFalcon’s Invoke-Loop function handles pagination automatically:

Initial Request

PSFalcon makes the first API request with your specified parameters.

Response Analysis

The response includes pagination metadata:

total - Total number of results available
offset or after or next_token - Token for next page
Current count of retrieved results

Automatic Iteration

If -All is specified and more results exist, PSFalcon:

Calculates the next offset/token
Makes subsequent requests automatically
Outputs results as they’re received
Continues until all results are retrieved

Using the -All Parameter

The simplest way to retrieve all results:

# Retrieve all hosts (up to API limits)
Get-FalconHost -All

# Retrieve all Windows hosts
Get-FalconHost -Filter "platform_name:'Windows'" -All

# Retrieve all hosts with full details
Get-FalconHost -All -Detailed

# Retrieve all hosts sorted by hostname
Get-FalconHost -All -Sort 'hostname.asc'

Pagination Parameters

PSFalcon commands support various pagination parameters:

-Limit

Maximum number of results per request.

# Get first 100 hosts
Get-FalconHost -Limit 100

# Different endpoints have different max limits
# From devices.ps1:165: Max is 5000 for Get-FalconHost
Get-FalconHost -Limit 5000

When used with -All, sets the page size for each request.

-Offset

Position to begin retrieving results (zero-based).

# Skip first 100 hosts
Get-FalconHost -Offset 100 -Limit 50

# Manual pagination
$Page1 = Get-FalconHost -Limit 100 -Offset 0
$Page2 = Get-FalconHost -Limit 100 -Offset 100
$Page3 = Get-FalconHost -Limit 100 -Offset 200

-All

Automatically retrieve all available results.

# PSFalcon handles pagination internally
$AllHosts = Get-FalconHost -All

Write-Host "Retrieved $($AllHosts.Count) total hosts"

-Total

Return only the total count, not the results.

# Get count without retrieving data
$Count = Get-FalconHost -Total

Write-Host "Total hosts: $Count"

Automatic Limit Optimization

From /home/daytona/workspace/source/private/Private.ps1:732-737, when using -All without -Limit:

# PSFalcon automatically sets Limit to the maximum allowed for the endpoint
Get-FalconHost -All

# Equivalent to:
Get-FalconHost -All -Limit 5000  # Max for this endpoint

This optimizes performance by reducing the number of API requests needed.

Pagination Token Types

From /home/daytona/workspace/source/private/Private.ps1:621-630, PSFalcon supports multiple pagination methods:

Pagination Token Types

Token Type	Description	Example Endpoints
`offset`	Numeric position in results	Most query endpoints
`after`	Cursor-based pagination	Scroll endpoints
`next_token`	Opaque pagination token	Some newer APIs

PSFalcon automatically detects and uses the appropriate pagination method.

Progress Tracking

From /home/daytona/workspace/source/private/Private.ps1:655, PSFalcon logs progress to the verbose stream:

# Enable verbose output to see pagination progress
Get-FalconHost -All -Verbose

# Output:
# VERBOSE: 14:23:45 [Get-FalconHost] Retrieved 5000 of 12500
# VERBOSE: 14:23:47 [Get-FalconHost] Retrieved 10000 of 12500
# VERBOSE: 14:23:49 [Get-FalconHost] Retrieved 12500 of 12500

Response Metadata

Every paginated response includes metadata:

# Use -RawOutput to see full response including metadata
$Response = Get-FalconHost -Limit 100 -RawOutput

$Response.meta.pagination
# total : 5000
# offset : 0
# limit : 100

The -RawOutput parameter is available on many commands to return the complete API response including metadata.

Endpoint-Specific Limits

From /home/daytona/workspace/source/public/devices.ps1:205-216, different endpoints have different maximum limits:

# Get-FalconHost with different parameter sets:

# Default queries: max 500
Get-FalconHost -Filter "hostname:'*'" -Limit 500

# Entity retrieval by ID: max 5000
Get-FalconHost -Id @($Ids) -Limit 5000

# Online state: max 100
Get-FalconHost -Id @($Ids) -State -Limit 100

# Login history: max 10
Get-FalconHost -Id @($Ids) -Login -Limit 10

PSFalcon enforces these limits automatically and will adjust your -Limit value if it exceeds the maximum.

Manual Pagination

For advanced scenarios, you can manually control pagination:

$Offset = 0
$Limit = 1000
$AllResults = @()

do {
    $Results = Get-FalconHost -Limit $Limit -Offset $Offset
    $AllResults += $Results
    $Offset += $Limit
    
    Write-Host "Retrieved $($AllResults.Count) hosts so far..."
    
} while ($Results.Count -eq $Limit)

Write-Host "Total: $($AllResults.Count) hosts"

# Get total count first
$Total = Get-FalconHost -Filter "platform_name:'Windows'" -Total

Write-Host "Retrieving $Total hosts..."

$Offset = 0
$Limit = 5000
$AllResults = @()

while ($AllResults.Count -lt $Total) {
    $Results = Get-FalconHost -Filter "platform_name:'Windows'" -Limit $Limit -Offset $Offset
    $AllResults += $Results
    $Offset += $Limit
    
    Write-Progress -Activity "Retrieving hosts" -PercentComplete (($AllResults.Count / $Total) * 100)
}

Write-Host "Complete: $($AllResults.Count) hosts"

# Process results in batches to reduce memory usage
$Offset = 0
$Limit = 1000

do {
    $Batch = Get-FalconHost -Limit $Limit -Offset $Offset
    
    # Process this batch immediately
    foreach ($Host in $Batch) {
        # Do something with each host
        Write-Output $Host | Export-Csv -Path "hosts.csv" -Append
    }
    
    $Offset += $Limit
    
} while ($Batch.Count -eq $Limit)

Performance Considerations

Use Maximum Limit

Set -Limit to the maximum allowed for the endpoint to minimize API calls:

# Good: 1 request for 5000 hosts
Get-FalconHost -Limit 5000

# Less efficient: 50 requests for 5000 hosts
Get-FalconHost -Limit 100 -All

Filter Early

Apply filters to reduce the result set size:

# Good: Only retrieves Windows hosts
Get-FalconHost -Filter "platform_name:'Windows'" -All

# Less efficient: Retrieves all hosts, filters client-side
Get-FalconHost -All | Where-Object { $_.platform_name -eq 'Windows' }

Process Incrementally

For very large result sets, process batches instead of loading everything into memory:

# Memory efficient
Get-FalconHost -Limit 5000 | 
    Where-Object { $_.status -eq 'normal' } |
    Export-Csv -Path "hosts.csv"

# Or use manual pagination with processing

Token Refresh During Pagination

From /home/daytona/workspace/source/private/Private.ps1:635-638, PSFalcon automatically refreshes authentication tokens during long pagination operations:

# No action needed - tokens are refreshed automatically
Get-FalconHost -All  # May take several minutes for large datasets

# PSFalcon checks token expiration before each request
# If token expires in < 240 seconds, it's automatically refreshed

Handling Pagination Errors

From /home/daytona/workspace/source/private/Private.ps1:658-660:

try {
    $Hosts = Get-FalconHost -All
} catch {
    if ($_.Exception.Message -match 'missing pagination token') {
        Write-Warning "Pagination was interrupted"
        Write-Warning "Partial results may be available in `$Hosts"
        
        # Retry or handle partial results
    } else {
        throw $_
    }
}

Common Patterns

# Retrieve all hosts and export to CSV
Get-FalconHost -All -Detailed | Export-Csv -Path "all_hosts.csv" -NoTypeInformation

# Get all hosts and count by platform
$Hosts = Get-FalconHost -All

$Hosts | Group-Object -Property platform_name | 
    Select-Object Name, Count | 
    Sort-Object -Property Count -Descending

# Get all Windows hosts with detailed info
$WindowsHosts = Get-FalconHost -Filter "platform_name:'Windows'" -All -Detailed

Write-Host "Found $($WindowsHosts.Count) Windows hosts"

# Output results as they're retrieved
Get-FalconHost -All | ForEach-Object {
    [PSCustomObject]@{
        Hostname = $_.hostname
        LastSeen = $_.last_seen
        Platform = $_.platform_name
    }
} | Format-Table -AutoSize

Scroll Endpoints

Some endpoints use scroll-based pagination with the after token:

# Scroll endpoints automatically use the 'after' token
Get-FalconHost -All  # Uses /devices/queries/devices-scroll/v1:get

# PSFalcon detects and uses the 'after' token from the response
# No manual handling required

From /home/daytona/workspace/source/private/Private.ps1:622-624, the after token is automatically detected and used.

Best Practices

Use -All for Complete Datasets

Let PSFalcon handle pagination automatically:

# Recommended
$AllHosts = Get-FalconHost -Filter "status:'normal'" -All

Set Appropriate Limits

Use maximum limits with -All for better performance:

# Optimal: Fewer API calls
Get-FalconHost -All -Limit 5000

Check Totals First for Planning

Use -Total to understand dataset size:

$Count = Get-FalconHost -Filter "platform_name:'Linux'" -Total

if ($Count -gt 10000) {
    Write-Warning "Large dataset detected: $Count hosts"
    # Adjust strategy accordingly
}

Handle Interruptions

Implement error handling for large operations:

try {
    $Results = Get-FalconHost -All -ErrorAction Stop
} catch {
    Write-Error "Pagination failed: $_"
    # Implement retry logic or save partial results
}

Monitor Progress with -Verbose

Track long-running operations:

Get-FalconHost -All -Verbose | Export-Csv -Path "hosts.csv"
# See progress in verbose output

Most PSFalcon Get-* commands support pagination:

Get-FalconHost - Retrieve hosts with pagination
Get-FalconDetect - Retrieve detections with pagination
Get-FalconIncident - Retrieve incidents with pagination
Get-FalconAlert - Retrieve alerts with pagination

All use the same pagination patterns described in this guide.

Next Steps

Filtering

Learn FQL syntax to reduce result sets before pagination

Authentication

Understand token management during long operations

Get Started

Core Concepts

Guides

Overview

Using the -All Parameter

Automatic Limit Optimization

Progress Tracking

Response Metadata

Endpoint-Specific Limits

Performance Considerations

Common Patterns

Scroll Endpoints

Best Practices

Next Steps

Filtering

Authentication

​Overview

​How Pagination Works

​Using the -All Parameter

​Pagination Parameters

​Automatic Limit Optimization

​Pagination Token Types

​Progress Tracking

​Response Metadata

​Endpoint-Specific Limits

​Manual Pagination

​Performance Considerations

​Token Refresh During Pagination

​Handling Pagination Errors

​Common Patterns

​Scroll Endpoints

​Best Practices

​Related Commands

​Next Steps

Filtering

Authentication

Overview

How Pagination Works

Using the -All Parameter

Pagination Parameters

Automatic Limit Optimization

Pagination Token Types

Progress Tracking

Response Metadata

Endpoint-Specific Limits

Manual Pagination

Performance Considerations

Token Refresh During Pagination

Handling Pagination Errors

Common Patterns

Scroll Endpoints

Best Practices

Related Commands

Next Steps