Platform Pagination
Efficiently retrieve large datasets using limit and offset query parameters
Platform pagination enables efficient retrieval of large datasets through standardized limit and offset query parameters across all list endpoints.
Platform pagination enables efficient retrieval of large datasets through standardized limit and offset query parameters across all list endpoints.
from praisonaiagents import Agent
agent = Agent(name="api-helper", instructions="Fetch large issue lists safely.")
agent.start("List the next page of open issues after the first 50.")The user pages through large API result sets with limit and offset without loading entire tables at once.
Quick Start
- Simple Page Request
Get the first 10 items from any list endpoint:
bash TOKEN="your-jwt-token" WS_ID="workspace-id" curl -s "http://localhost:8000/api/v1/workspaces/$WS_ID/issues/?limit=10&offset=0" \ -H "Authorization: Bearer $TOKEN" - Iterate Through Pages
Use offset to get subsequent pages:
bash # First page (items 0-9) curl -s "http://localhost:8000/api/v1/workspaces/$WS_ID/issues/?limit=10&offset=0" # Second page (items 10-19) curl -s "http://localhost:8000/api/v1/workspaces/$WS_ID/issues/?limit=10&offset=10" # Third page (items 20-29) curl -s "http://localhost:8000/api/v1/workspaces/$WS_ID/issues/?limit=10&offset=20"
How It Works
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
limit | int | 50 | 1–200 | Maximum items to return |
offset | int | 0 | ≥ 0 | Number of items to skip |
Paginated Endpoints
All platform list endpoints support pagination:
| Endpoint | Description | Default Limit | Max Limit |
|---|---|---|---|
GET /api/v1/workspaces/ | List workspaces | 50 | 200 |
GET /api/v1/workspaces/{ws_id}/projects/ | List projects | 50 | 200 |
GET /api/v1/workspaces/{ws_id}/issues/ | List issues | 50 | 200 |
GET /api/v1/workspaces/{ws_id}/agents/ | List agents | 50 | 200 |
GET /api/v1/workspaces/{ws_id}/activity | List activities | 50 | 200 |
GET /api/v1/workspaces/{ws_id}/issues/{id}/activity | List issue activities | 50 | 200 |
Common Patterns
Python SDK
import asyncio
import httpx
async def fetch_all_issues(ws_id: str, token: str):
"""Fetch all issues using pagination."""
base = "http://localhost:8000/api/v1"
headers = {"Authorization": f"Bearer {token}"}
all_issues = []
offset = 0
page_size = 50
async with httpx.AsyncClient() as client:
while True:
resp = await client.get(
f"{base}/workspaces/{ws_id}/issues/",
params={"limit": page_size, "offset": offset},
headers=headers
)
page = resp.json()
if not page:
break # No more results
all_issues.extend(page)
if len(page) < page_size:
break # Last page
offset += page_size
return all_issues
async def main():
issues = await fetch_all_issues("your-ws-id", "your-token")
print(f"Total issues: {len(issues)}")
asyncio.run(main())JavaScript
async function fetchAllIssues(wsId, token) {
const base = "http://localhost:8000/api/v1";
const headers = { Authorization: `Bearer ${token}` };
const allIssues = [];
let offset = 0;
const pageSize = 50;
while (true) {
const response = await fetch(
`${base}/workspaces/${wsId}/issues/?limit=${pageSize}&offset=${offset}`,
{ headers }
);
const page = await response.json();
if (!page.length) break; // No more results
allIssues.push(...page);
if (page.length < pageSize) break; // Last page
offset += pageSize;
}
return allIssues;
}
// Usage
const issues = await fetchAllIssues("your-ws-id", "your-token");
console.log(`Total issues: ${issues.length}`);cURL Script
#!/bin/bash
TOKEN="your-jwt-token"
WS_ID="workspace-id"
BASE_URL="http://localhost:8000/api/v1"
OFFSET=0
PAGE_SIZE=50
ALL_ISSUES=()
while true; do
RESPONSE=$(curl -s "${BASE_URL}/workspaces/${WS_ID}/issues/?limit=${PAGE_SIZE}&offset=${OFFSET}" \
-H "Authorization: Bearer ${TOKEN}")
# Check if response is empty array
if [[ "$RESPONSE" == "[]" ]]; then
break
fi
# Count items in response
ITEM_COUNT=$(echo "$RESPONSE" | jq '. | length')
if [[ $ITEM_COUNT -eq 0 ]]; then
break
fi
echo "Fetched $ITEM_COUNT items (offset: $OFFSET)"
# Break if less than page size (last page)
if [[ $ITEM_COUNT -lt $PAGE_SIZE ]]; then
break
fi
OFFSET=$((OFFSET + PAGE_SIZE))
done
echo "Pagination complete"Best Practices
Choose appropriate page sizes
Use larger page sizes (100-200) for bulk operations, smaller sizes (10-50) for user interfaces. Consider network latency and memory constraints.
Handle empty responses
Always check for empty arrays [] to detect the end of results. Don’t rely solely on response length being less than the page size.
Implement retry logic
Add exponential backoff for failed requests and timeout handling for reliable pagination in production environments.
Cache total counts separately
Pagination doesn’t return total counts. If needed, make separate count requests or cache totals to avoid expensive calculations.
Testing
Test pagination behavior with these commands:
# Test boundary conditions
pytest tests/test_new_gaps.py::TestPagination -v
# Test API integration
pytest tests/test_new_api_integration.py::TestPaginationAPI -v
# Manual testing with curl
curl -s "http://localhost:8000/api/v1/workspaces/test/issues/?limit=1&offset=0"
curl -s "http://localhost:8000/api/v1/workspaces/test/issues/?limit=999&offset=0" # Should limit to 200