API Pagination Debugging

npx skills add majiayu000/claude-skill-registry --skill api-pagination-debugging --agent claude-code

Same command for any agent — swap --agent for codex, cursor, copilot.

# API Pagination Debugging > **Purpose**: Systematically diagnose and fix pagination failures that prevent complete data import from APIs ## Core Principles ### 1. Verify API Response Structure Before Assuming Never assume pagination fields based on documentation or other endpoints. Always test actual responses: ```bash curl -s API_ENDPOINT | jq 'keys' ``` Different API versions or endpoints may use different pagination patterns even within the same service. ### 2. Match Pagination Logic to API Design APIs use distinct pagination patterns that require different implementations: - **Cursor-based**: `{nextPageCursor, results}` - use cursor param - **Page-based**: `{page, total_pages, results}` - use page number param - **Offset-based**: `{offset, limit, total}` - use offset/limit params - **Link-based**: `{next, previous, results}` - follow next URL Using the wrong pattern causes pagination to stop after first page. ### 3. Optimize Page Size for Efficiency Most APIs support configurable page sizes (e.g., 50-1000 items per page). Using maximum page_size: - Reduces total API calls (20x fewer calls with 1000 vs 50) - Decreases network overhead - Minimizes rate limit exposure - Speeds up

curl -s API_ENDPOINT | jq 'keys'
Fetch first page and check structure
curl -s -H "Authorization: Token $TOKEN" \
Expected output reveals actual fields:
NOT ["count", "next", "previous", "results"]
Get page 1
Extract cursor
Get page 2 using cursor
curl -s API_ENDPOINT | jq '.'
curl API | jq 'keys'