Skip to main content
Most list endpoints in the Poelis Public API support pagination to help you efficiently retrieve large datasets.

​
Pagination Parameters

All paginated endpoints accept these query parameters:
  • limit: Number of items to return per page (1-200, default: 50)
  • offset: Number of items to skip from the beginning (default: 0)

​
Basic Usage

# Get first page (50 items)
GET /v1/public/workspaces?limit=50&offset=0

# Get second page (next 50 items)
GET /v1/public/workspaces?limit=50&offset=50

# Get third page (next 50 items)
GET /v1/public/workspaces?limit=50&offset=100

​
Response Format

Paginated responses include:
  • items: Array of resources
  • count: Number of items in the current response (not total count)
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Workspace 1"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Workspace 2"
    }
  ],
  "count": 2
}

​
Pagination Strategies

​
Offset-Based Pagination

Use offset and limit to page through results: 
def fetch_all_workspaces(api_key, base_url):
    all_workspaces = []
    offset = 0
    limit = 50
    
    while True:
        response = requests.get(
            f"{base_url}/v1/public/workspaces",
            headers={"Authorization": f"Bearer {api_key}"},
            params={"limit": limit, "offset": offset}
        )
        response.raise_for_status()
        data = response.json()
        
        all_workspaces.extend(data["items"])
        
        # If we got fewer items than requested, we've reached the end
        if len(data["items"]) < limit:
            break
        
        offset += limit
    
    return all_workspaces

​
Best Practices

Choose Appropriate Limits

Use limit=50 for most cases. Increase only if needed, up to 200

Handle Empty Results

Check if count === 0 to detect end of results