Pagination

Most list endpoints in the Qarion API return paginated results to keep response sizes manageable. Understanding how pagination works is essential for building integrations that need to retrieve large datasets efficiently.

Standard Pattern

All paginated endpoints follow a consistent pattern using two query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
size	integer	20	Items per page

The page parameter is 1-indexed, meaning the first page is page=1. The size parameter controls how many items each page contains, defaulting to 20 if not specified.

Request

To request a specific page with a custom page size, include both parameters in the query string:

curl -X GET "https://api.qarion.com/catalog/spaces/analytics/products?page=2&size=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

Every paginated response includes metadata alongside the results, so your application always knows where it is within the full result set:

{
  "items": [...],
  "total": 142,
  "page": 2,
  "size": 50
}

Field	Description
items	Array of results for current page
total	Total count across all pages
page	Current page number
size	Items per page

The total field is particularly useful because it lets you calculate the full page count and determine whether there are more pages to fetch, without making an additional request.

Calculating Pages

Using the response metadata, you can compute navigation state for your UI or iteration logic:

const totalPages = Math.ceil(response.total / response.size);
const hasNextPage = response.page < totalPages;
const hasPrevPage = response.page > 1;

Limits

The API enforces bounds on pagination parameters to prevent excessively large responses:

Constraint	Value
Maximum size	100
Default size	20
Minimum page	1

If you request a size greater than 100, the API silently caps it at 100. This ensures that individual responses remain fast and predictable in size.

Iteration Example

When you need to retrieve all items across multiple pages — for example, to export your full product catalog — iterate through pages until you've consumed the entire result set:

import requests

def get_all_products(space_slug, api_key):
    products = []
    page = 1
    
    while True:
        response = requests.get(
            f"https://api.qarion.com/catalog/spaces/{space_slug}/products",
            headers={"Authorization": f"Bearer {api_key}"},
            params={"page": page, "size": 100}
        )
        data = response.json()
        products.extend(data["items"])
        
        if page * data["size"] >= data["total"]:
            break
        page += 1
    
    return products

This approach uses the maximum page size of 100 to minimize the number of round trips, and stops as soon as the total has been reached.

Performance Tips

Pagination is straightforward, but a few practices can help you keep your integration efficient. Use filters (such as search, tag, or type parameters) to reduce the result set before paginating — fetching 50 filtered results is much faster than paginating through 5,000 products to find the ones you need.

Request only the pages you actually need rather than exhaustively fetching everything. If your users are browsing a paginated list, there's no reason to preload all pages upfront. Cache results when the underlying data doesn't change frequently — product catalogs, for example, typically update infrequently enough that caching for a few minutes is safe and dramatically reduces API load.

Finally, for specific lookups where you know the name or slug of what you're looking for, use the search endpoint instead of iterating through pages. Search is indexed and much faster than scanning the full catalog.

Endpoints with Pagination

The following endpoints support the standard pagination pattern described above:

Endpoint	Default Size
Products list	20
Issues list	20
Meetings list	20
Quality checks	20
Alerts	20
Sync history	10