> ## 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. 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:

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

<Note>
  Some endpoints use `meta` instead of `pagination`, and `current_page` instead of `page`. Always check the endpoint documentation for the exact response structure.
</Note>

## Pagination Patterns

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

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

    **Endpoints:** `/v1/vendors`, `/v1/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/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/collections`

    Include `page` and `page_size` in the request body. Response includes a `meta` object (not `pagination`) with `current_page` (not `page`).

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

    ```python theme={null}
    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']}")
    ```

    <Note>
      For `/v1/products/{execution_id}`, the pagination response uses `limit` instead of `page_size`.
    </Note>

    ### 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/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)
    ```
  </Tab>

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

    **Endpoints:** `/v1/vendors`, `/v1/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/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/collections`

    Include `page` and `page_size` in the request body. Response includes a `meta` object (not `pagination`) with `current_page` (not `page`).

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

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

    <Note>
      For `/v1/products/{execution_id}`, the pagination response uses `limit` instead of `page_size`.
    </Note>

    ### 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/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
      }
    };
    ```
  </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>

## Important Notes

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

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