The Catalog API uses page-based pagination to efficiently handle large result sets. Different endpoints use slightly different pagination patterns, but all provide metadata to help you navigate through results.
Most paginated endpoints return a pagination object with the following structure:
{
"data": [...], // or "listings", "collections", etc.
"pagination": { // or "meta" for some endpoints
"page": 1, // Current page number (or "current_page" for some endpoints)
"page_size": 20, // Items per page (or "limit" for execution endpoints)
"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
}
}
Some endpoints use meta instead of pagination, and current_page instead of page. Always check the endpoint documentation for the exact response structure.
Pattern 1: GET Endpoints with Query Parameters
Endpoints: /v1/vendors, /v1/usageUse page and page_size as query parameters. Response includes a pagination object.import requests
response = requests.get(
'https://api.getcatalog.ai/v1/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: /v1/listings, /v1/collectionsInclude page and page_size in the request body. Response includes a meta object (not pagination) with current_page (not page).import requests
response = requests.post(
'https://api.getcatalog.ai/v1/listings',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'vendor': 'nike',
'page': 1,
'page_size': 20
}
)
data = response.json()
# Note: uses "meta" not "pagination", and "current_page" not "page"
print(f"Found {data['meta']['total_items']} listings")
print(f"Page {data['meta']['current_page']} of {data['meta']['total_pages']}")
Pattern 3: Execution Status Endpoints
Endpoints: /v1/products/{execution_id}Use page and limit as query parameters (only when status is "completed"). Response includes a pagination object.import requests
response = requests.get(
f'https://api.getcatalog.ai/v1/products/{execution_id}',
headers={'x-api-key': 'YOUR_API_KEY'},
params={'page': 1, 'limit': 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']}")
For /v1/products/{execution_id}, the pagination response uses limit instead of page_size.
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/v1/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: /v1/vendors, /v1/usageUse page and page_size as query parameters. Response includes a pagination object.const response = await fetch(
'https://api.getcatalog.ai/v1/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: /v1/listings, /v1/collectionsInclude page and page_size in the request body. Response includes a meta object (not pagination) with current_page (not page).const response = await fetch('https://api.getcatalog.ai/v1/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();
// Note: uses "meta" not "pagination", and "current_page" not "page"
console.log(`Found ${data.meta.total_items} listings`);
console.log(`Page ${data.meta.current_page} of ${data.meta.total_pages}`);
Pattern 3: Execution Status Endpoints
Endpoints: /v1/products/{execution_id}Use page and limit as query parameters (only when status is "completed"). Response includes a pagination object.const response = await fetch(
`https://api.getcatalog.ai/v1/products/${executionId}?page=1&limit=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}`);
}
For /v1/products/{execution_id}, the pagination response uses limit instead of page_size.
Basic Implementation Example
Here’s a simple example of implementing pagination:const fetchVendors = async (page = 1) => {
const response = await fetch(
`https://api.getcatalog.ai/v1/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)
Important Notes
Response Structure Variations:
- Different endpoints return data in different fields (
data, listings, collections, etc.)
- Some endpoints use
pagination object, others use meta object
- Some use
page in response, others use current_page
- Always check the endpoint documentation for the exact response structure
Endpoints Without Pagination:
/v1/agentic-search - Returns up to 8 products, no pagination/v1/agentic-search-mini - Returns up to 10 products, no pagination- List executions endpoints (
/v1/crawl) - Use limit parameter but don’t return pagination metadata
