Skip to main content
🤖 Judit API pagination does not use cursors. It is based on the Offset pattern, using exclusively the query parameters page (page number) and page_size (number of items). The strict maximum limit for page_size is 1000 items. Pagination metadata is returned at the root of the response object.

​
How Pagination Works

​
Query Parameters (Request)

When performing listings (such as fetching the history of requests or trackings), you can send the following parameters in the URL:
ParameterTypeDefaultDescription
pageinteger1Desired page number (1-based).
page_sizeinteger20Number of items returned per page. Maximum allowed: 1000. Recommendation: Keep between 10 and 100 for better response time.

​
Response Structure (Payload)

Responses from paginated endpoints always return navigation metadata at the root of the JSON, and the items themselves usually come in the page_data array. 
{
  "page": 1,              // Current page being returned
  "page_count": 20,       // Number of items present in this specific page
  "all_pages_count": 10,  // Total number of pages available for this query
  "all_count": 200,       // Absolute total of items found in the database
  "page_data": [          // Array containing the query objects
    { ... }, 
    { ... }
  ]
}

​
Practical Examples

​
Basic Query with Pagination

Below, we show how to fetch the first page of requests and iterate over the data. 
# 1. Fetching the first page (10 items)
curl -X GET "https://requests.prod.judit.io/requests?page=1&page_size=10" \
  -H "api-key: $JUDIT_API_KEY"

# 2. Fetching a specific page (e.g., page 3, 25 items)
curl -X GET "https://requests.prod.judit.io/requests?page=3&page_size=25" \
  -H "api-key: $JUDIT_API_KEY"

​
Optimizations and Best Practices

To handle large data volumes efficiently and without being blocked by the API, follow the recommendations below.

​
1. Choosing the right page_size

Adjust the page size according to your application’s needs, always keeping the 1000-item limit per request in mind. 
# ✅ GOOD: For UI rendering (tables, grids)
small_page = get_requests_page(page=1, page_size=10)

# ✅ GOOD: For async batch processing (ETL, migrations)
large_page = get_requests_page(page=1, page_size=100) 

# ❌ ERROR: Exceeds the maximum allowed by the API
# invalid_page = get_requests_page(page=1, page_size=1001)

​
2. Rate Limit Control (Safe Iteration)

The Judit API has strict per-minute request limits. When building loops to extract all pages, it is mandatory to implement a small delay between calls to avoid the 429 Too Many Requests error. 
import time

def fetch_all_data_safely(delay_seconds=0.2):
    """Extracts all pages while respecting the API's request limit"""
    current_page = 1
    all_extracted_items = []
    
    while True:
        # Using a safe page_size (below the 1000 limit)
        data = get_requests_page(page=current_page, page_size=50)
        
        # Stop if there is no data or the page_data key is missing
        if not data or not data.get('page_data'):
            break
            
        all_extracted_items.extend(data['page_data'])
        print(f"Extracted: Page {current_page}/{data.get('all_pages_count')}. Total so far: {len(all_extracted_items)}")
        
        # Check if we've reached the last page
        if current_page >= data.get('all_pages_count', 1):
            print("Extraction completed successfully.")
            break
        
        current_page += 1
        
        # ⚠️ CRITICAL: Pause so we don't blow past the Rate Limit (e.g., 180 req/min)
        time.sleep(delay_seconds)
        
    return all_extracted_items
Note on Parallel Processing: We removed the concurrent processing (threads) example because firing multiple pages in parallel will almost certainly trigger Rate Limit blocking (Error 429), unless your application has robust distributed queue management. We always recommend sequential processing with a delay or controlled queues.

​
Next Steps

  • 👉 Rate Limits: Understand your account’s request quotas.
  • 👉 Authentication: Review how to send your credentials.
  • 👉 Endpoints: Explore the resources that support listings.