> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcatalog.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Navigate through large result sets efficiently with 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:

```json theme={null}
{
  "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
  }
}
```

<Note>
  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.
</Note>

## Pagination Patterns

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

<Tabs>
  <Tab title="Python">
    ### Pattern 1: GET Endpoints with Query Parameters

    **Endpoints:** `/v2/vendors`, `/v2/usage`

    Use `page` and `page_size` as query parameters. Response includes a `pagination` object.

    ```python theme={null}
    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/collections`

    Use `page` and `page_size` as query parameters (along with endpoint-specific params like `vendor`). Response includes a `pagination` object.

    ```python theme={null}
    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.

    ```python theme={null}
    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:

    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="JavaScript">
    ### Pattern 1: GET Endpoints with Query Parameters

    **Endpoints:** `/v2/vendors`, `/v2/usage`

    Use `page` and `page_size` as query parameters. Response includes a `pagination` object.

    ```javascript theme={null}
    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/collections`

    Use `page` and `page_size` as query parameters (along with endpoint-specific params like `vendor`). Response includes a `pagination` object.

    ```javascript theme={null}
    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.

    ```javascript theme={null}
    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:

    ```javascript theme={null}
    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
      }
    };
    ```
  </Tab>
</Tabs>

## Best Practices

### Using has\_next and has\_prev

The `has_next` and `has_prev` boolean fields make it easy to implement navigation controls:

```javascript theme={null}
// 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

<Tip>
  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)
</Tip>