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.

python
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.

Diagram

Pagination Flow

📝 Request

🔍 Limit & Offset

🔄 Process

📋 Page Results

⚡ Return JSON

Quick Start

  1. 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"
  2. 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

Diagram
DatabaseAPIClientDatabaseAPIClientGET /issues/?limit=50&offset=100SELECT * LIMIT 50 OFFSET 10050 recordsJSON response
ParameterTypeDefaultRangeDescription
limitint501–200Maximum items to return
offsetint0≥ 0Number of items to skip

Paginated Endpoints

All platform list endpoints support pagination:

EndpointDescriptionDefault LimitMax Limit
GET /api/v1/workspaces/List workspaces50200
GET /api/v1/workspaces/{ws_id}/projects/List projects50200
GET /api/v1/workspaces/{ws_id}/issues/List issues50200
GET /api/v1/workspaces/{ws_id}/agents/List agents50200
GET /api/v1/workspaces/{ws_id}/activityList activities50200
GET /api/v1/workspaces/{ws_id}/issues/{id}/activityList issue activities50200

Common Patterns

Python SDK

python
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

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

bash
#!/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:

bash
# 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

Related