Pagination

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.

Pagination Response Structure

Paginated endpoints return a consistent structure:

{
  "data": [{ "_truncated": "Additional items omitted for display" }],
  "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.

Pagination Patterns

The Catalog API uses consistent pagination patterns. Examples for each pattern are shown below:

Python
JavaScript

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: GET Endpoints with Query Parameters (listings, collections)

Endpoints: /v2/listings, /v2/collectionsUse page and page_size as query parameters (along with endpoint-specific params like vendor). Response includes a pagination object.

import requests

response = requests.get(
  'https://api.getcatalog.ai/v2/listings',
  headers={'x-api-key': 'YOUR_API_KEY'},
  params={
    'vendor': 'nike.com',
    '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: GET Endpoints with Query Parameters (listings, collections)

Endpoints: /v2/listings, /v2/collectionsUse page and page_size as query parameters (along with endpoint-specific params like vendor). Response includes a pagination object.

const params = new URLSearchParams({
  vendor: 'nike.com',
  page: '1',
  page_size: '20'
});

const response = await fetch(
  `https://api.getcatalog.ai/v2/listings?${params}`,
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);

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)

Get Started

API Reference

Guides

Resources

Migration Guides

Pattern 1: GET Endpoints with Query Parameters

Pattern 2: GET Endpoints with Query Parameters (listings, collections)

Pattern 3: Execution Status Endpoints

Basic Implementation Example

Pattern 1: GET Endpoints with Query Parameters

Pattern 2: GET Endpoints with Query Parameters (listings, collections)

Pattern 3: Execution Status Endpoints

Basic Implementation Example

Best Practices

Using has_next and has_prev

Page Size Recommendations

​Pagination Response Structure

​Pagination Patterns

​Pattern 1: GET Endpoints with Query Parameters

​Pattern 2: GET Endpoints with Query Parameters (listings, collections)

​Pattern 3: Execution Status Endpoints

​Basic Implementation Example

​Pattern 1: GET Endpoints with Query Parameters

​Pattern 2: GET Endpoints with Query Parameters (listings, collections)

​Pattern 3: Execution Status Endpoints

​Basic Implementation Example

​Best Practices

​Using has_next and has_prev

​Page Size Recommendations

Pagination Response Structure

Pagination Patterns

Pattern 1: GET Endpoints with Query Parameters

Pattern 2: GET Endpoints with Query Parameters (listings, collections)

Pattern 3: Execution Status Endpoints

Basic Implementation Example

Pattern 1: GET Endpoints with Query Parameters

Pattern 2: GET Endpoints with Query Parameters (listings, collections)

Pattern 3: Execution Status Endpoints

Basic Implementation Example

Best Practices

Using has_next and has_prev

Page Size Recommendations