The Catalog API uses page-based pagination to efficiently handle large result sets. All endpoints provide consistent pagination metadata to help you navigate through results.
Paginated endpoints return a consistent structure:
{
"data": [...], // Array of results (products, listings, etc.)
"pagination": {
"page": 1, // Current page number
"page_size": 20, // Items per page
"total_items": 100, // Total matching items
"total_pages": 5, // Total pages available
"has_next": true, // Whether there is a next page
"has_prev": false // Whether there is a previous page
}
}
All endpoints consistently return data in a data array and use page_size for pagination parameters. The pagination object structure is consistent across all endpoints.
Pattern 1: GET Endpoints with Query Parameters
Endpoints: /v2/vendors, /v2/usageUse page and page_size as query parameters. Response includes a pagination object.import requests
response = requests.get(
'https://api.getcatalog.ai/v2/vendors',
headers={'x-api-key': 'YOUR_API_KEY'},
params={'page': 1, 'page_size': 20}
)
data = response.json()
print(f"Found {data['pagination']['total_items']} vendors")
print(f"Page {data['pagination']['page']} of {data['pagination']['total_pages']}")
Pattern 2: POST Endpoints with Body Parameters
Endpoints: /v2/listings, /v2/collections, /v2/agentic-searchInclude page and page_size in the request body. Response includes a pagination object.import requests
response = requests.post(
'https://api.getcatalog.ai/v2/listings',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'vendor': 'nike',
'page': 1,
'page_size': 20
}
)
data = response.json()
print(f"Found {data['pagination']['total_items']} listings")
print(f"Page {data['pagination']['page']} of {data['pagination']['total_pages']}")
Pattern 3: Execution Status Endpoints
Endpoints: /v2/extract/{execution_id}Use page and page_size as query parameters (only when status is "completed"). Response includes a pagination object.import requests
response = requests.get(
f'https://api.getcatalog.ai/v2/extract/{execution_id}',
headers={'x-api-key': 'YOUR_API_KEY'},
params={'page': 1, 'page_size': 50}
)
data = response.json()
if data['status'] == 'completed':
print(f"Retrieved {len(data['data'])} products")
print(f"Page {data['pagination']['page']} of {data['pagination']['total_pages']}")
Basic Implementation Example
Here’s a simple example of implementing pagination:import requests
def fetch_vendors(page=1, page_size=20):
response = requests.get(
'https://api.getcatalog.ai/v2/vendors',
headers={'x-api-key': 'YOUR_API_KEY'},
params={'page': page, 'page_size': page_size}
)
return response.json()
# Navigate through pages
data = fetch_vendors(page=1)
pagination = data['pagination']
if pagination['has_next']:
next_page_data = fetch_vendors(page=pagination['page'] + 1)
Pattern 1: GET Endpoints with Query Parameters
Endpoints: /v2/vendors, /v2/usageUse page and page_size as query parameters. Response includes a pagination object.const response = await fetch(
'https://api.getcatalog.ai/v2/vendors?page=1&page_size=20',
{
headers: {
'x-api-key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();
console.log(`Found ${data.pagination.total_items} vendors`);
console.log(`Page ${data.pagination.page} of ${data.pagination.total_pages}`);
Pattern 2: POST Endpoints with Body Parameters
Endpoints: /v2/listings, /v2/collections, /v2/agentic-searchInclude page and page_size in the request body. Response includes a pagination object.const response = await fetch('https://api.getcatalog.ai/v2/listings', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
vendor: 'nike',
page: 1,
page_size: 20
})
});
const data = await response.json();
console.log(`Found ${data.pagination.total_items} listings`);
console.log(`Page ${data.pagination.page} of ${data.pagination.total_pages}`);
Pattern 3: Execution Status Endpoints
Endpoints: /v2/extract/{execution_id}Use page and page_size as query parameters (only when status is "completed"). Response includes a pagination object.const response = await fetch(
`https://api.getcatalog.ai/v2/extract/${executionId}?page=1&page_size=50`,
{
headers: {
'x-api-key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();
if (data.status === 'completed') {
console.log(`Retrieved ${data.data.length} products`);
console.log(`Page ${data.pagination.page} of ${data.pagination.total_pages}`);
}
Basic Implementation Example
Here’s a simple example of implementing pagination:const fetchVendors = async (page = 1) => {
const response = await fetch(
`https://api.getcatalog.ai/v2/vendors?page=${page}&page_size=20`,
{
headers: {
'x-api-key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();
return data;
};
// Navigate to next page
const handleNextPage = async (currentPage, pagination) => {
if (pagination.has_next) {
const data = await fetchVendors(currentPage + 1);
// Update your UI with data.data and data.pagination
}
};
// Navigate to previous page
const handlePrevPage = async (currentPage, pagination) => {
if (pagination.has_prev) {
const data = await fetchVendors(currentPage - 1);
// Update your UI with data.data and data.pagination
}
};
Best Practices
Using has_next and has_prev
The has_next and has_prev boolean fields make it easy to implement navigation controls:
// Enable/disable navigation buttons based on pagination state
<button
onClick={() => goToPage(pagination.page - 1)}
disabled={!pagination.has_prev}
>
Previous
</button>
<button
onClick={() => goToPage(pagination.page + 1)}
disabled={!pagination.has_next}
>
Next
</button>
Page Size Recommendations
Choose page sizes that balance performance and user experience:
- Mobile: 6-12 items per page
- Desktop: 12-24 items per page
- Maximum: 100 items per page (varies by endpoint)
