Pagination

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.

Pagination Response Structure

Most paginated endpoints return a pagination object with the following structure:

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

Pagination Patterns

The Catalog API uses three main pagination patterns depending on the endpoint type. Examples for each pattern are shown below:

Python
JavaScript

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

Get Started

API Reference

Guides

Resources

Pattern 1: GET Endpoints with Query Parameters

Pattern 2: POST Endpoints with Body Parameters

Pattern 3: Execution Status Endpoints

Basic Implementation Example

Pattern 1: GET Endpoints with Query Parameters

Pattern 2: POST Endpoints with Body Parameters

Pattern 3: Execution Status Endpoints

Basic Implementation Example

Best Practices

Using has_next and has_prev

Page Size Recommendations

Important Notes

​Pagination Response Structure

​Pagination Patterns

​Pattern 1: GET Endpoints with Query Parameters

​Pattern 2: POST Endpoints with Body Parameters

​Pattern 3: Execution Status Endpoints

​Basic Implementation Example

​Pattern 1: GET Endpoints with Query Parameters

​Pattern 2: POST Endpoints with Body Parameters

​Pattern 3: Execution Status Endpoints

​Basic Implementation Example

​Best Practices

​Using has_next and has_prev

​Page Size Recommendations

​Important Notes

Pagination Response Structure

Pagination Patterns

Pattern 1: GET Endpoints with Query Parameters

Pattern 2: POST Endpoints with Body Parameters

Pattern 3: Execution Status Endpoints

Basic Implementation Example

Pattern 1: GET Endpoints with Query Parameters

Pattern 2: POST Endpoints with Body Parameters

Pattern 3: Execution Status Endpoints

Basic Implementation Example

Best Practices

Using has_next and has_prev

Page Size Recommendations

Important Notes