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

# Get Product Listings

> Get product listings from a vendor with pagination. Optionally filter by collection URLs.

<Tip>
  **When to use:** Browse all products from a vendor or filter by specific collections. Use with [`POST /v1/collections`](/v1/api-reference/endpoints/get-collections) to discover available collections first.
</Tip>

## Request

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

<ParamField body="vendor" type="string" required>
  The vendor/brand name to filter by
</ParamField>

<ParamField body="page" type="number" optional>
  Page number for pagination (minimum: 1)
</ParamField>

<ParamField body="page_size" type="number" optional>
  Number of collection products per page (minimum: 1, maximum: 100, default: 10)
</ParamField>

<ParamField body="collection_urls" type="string[]" optional>
  Array of collection URLs to filter by. If provided, only listings from these collections will be returned.

  **URL sanitization:** URLs are sanitized and normalized on the backend; client-side sanitization is not required.
</ParamField>

## Response

<ResponseField name="listings" type="array">
  Array of listing objects

  <Expandable title="Listing Object">
    <ResponseField name="id" type="string">
      Unique identifier for the listing
    </ResponseField>

    <ResponseField name="url" type="string">
      Product URL
    </ResponseField>

    <ResponseField name="name" type="string" optional>
      Product name
    </ResponseField>

    <ResponseField name="images" type="array" optional>
      Array of product images
    </ResponseField>

    <ResponseField name="price" type="object" optional>
      Product price information
    </ResponseField>

    <ResponseField name="vendor" type="string">
      Vendor/brand name
    </ResponseField>

    <ResponseField name="first_seen_by_catalog" type="string">
      ISO 8601 timestamp when the product was first discovered by Catalog
    </ResponseField>

    <ResponseField name="last_updated_by_catalog" type="string">
      ISO 8601 timestamp when the product was last updated by Catalog
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata

  <Expandable title="Meta Object">
    <ResponseField name="total_items" type="number">
      Total number of listings matching the query
    </ResponseField>

    <ResponseField name="total_pages" type="number">
      Total number of pages available
    </ResponseField>

    <ResponseField name="current_page" type="number">
      Current page number
    </ResponseField>

    <ResponseField name="page_size" type="number">
      Number of items per page
    </ResponseField>

    <ResponseField name="has_next" type="boolean">
      Whether there is a next page
    </ResponseField>

    <ResponseField name="has_prev" type="boolean">
      Whether there is a previous page
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample dropdown>
  ```powershell cURL theme={null}
  curl -X POST https://api.getcatalog.ai/v1/listings \
    -H "x-api-key: $CATALOG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "vendor": "skims.com",
      "page": 1,
      "page_size": 2,
      "collection_urls": [
        "https://www.skims.com/collections/skims-sale",
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.getcatalog.ai/v1/listings', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      vendor: 'skims.com',
      page: 1,
      page_size: 2,
      collection_urls: [
        'https://www.skims.com/collections/skims-sale'
      ]
    })
  });

  const data = await response.json();
  console.log(`Found ${data.listings.length} listings`);
  console.log(`Page ${data.meta.current_page} of ${data.meta.total_pages}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.getcatalog.ai/v1/listings',
      headers={'x-api-key': 'YOUR_API_KEY'},
      json={
          'vendor': 'skims.com',
          'page': 1,
          'page_size': 2,
          'collection_urls': [
              'https://www.skims.com/collections/skims-sale'
          ]
      }
  )

  data = response.json()
  print(f"Found {len(data['listings'])} listings")
  print(f"Page {data['meta']['current_page']} of {data['meta']['total_pages']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "listings": [
      {
        "id": "b96df1e8-789f-4805-b212-6c68e2d994cc",
        "url": "https://www.skims.com/products/skims-flex-mens-9-inch-boxer-brief-gunmetal",
        "name": "SKIMS FLEX MENS 9\" BOXER BRIEF | GUNMETAL",
        "images": [
          {
            "id": "5db75d7d-1975-4dd2-b130-f33861090ecc",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SKIMS-UNDERWEAR-BO-BBR-5354M-GUN.jpg?v=1714773683",
            "width": 2000,
            "height": 2000,
            "position": 1
          },
          {
            "id": "2478d00a-bc6a-4ed5-95f6-03a53f9c6ece",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/BO-BBR-5354M-GUN-JJ-SKIMS-MENS_0223-FR.jpg?v=1714773683",
            "width": 2000,
            "height": 2000,
            "position": 2
          },
          {
            "id": "36afe867-ef13-4099-a34b-9fa0f31483ac",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/BO-BBR-5354M-GUN-JJ-SKIMS-MENS_0224-FR.jpg?v=1714773683",
            "width": 2000,
            "height": 2000,
            "position": 3
          },
          {
            "id": "e26a2514-8b2a-4ff0-8f6a-277f44b7898e",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/BO-BBR-5354M-GUN-JJ-SKIMS-MENS_0229-SD.jpg?v=1714773683",
            "width": 2000,
            "height": 2000,
            "position": 4
          },
          {
            "id": "c72ed9a0-56f3-4e1e-9323-582d96b232ff",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/BO-BBR-5354M-GUN-JJ-SKIMS-MENS_0233-BK.jpg?v=1714773683",
            "width": 2000,
            "height": 2000,
            "position": 5
          },
          {
            "id": "44d019fd-926b-486e-916c-19d4a73f39c6",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SKIMS-SKIMSSPORT-GUN-SW.jpg?v=1714773683",
            "width": 2000,
            "height": 2000,
            "position": 6
          }
        ],
        "price": {
          "currency": "USD",
          "current_value": 12,
          "compare_at_value": 26
        },
        "vendor": "skims.com",
        "first_seen_by_catalog": "2025-11-12T05:43:17.281203+00:00",
        "last_updated_by_catalog": "2025-11-12T05:43:17.281203+00:00"
      },
      {
        "id": "55f99a5e-7838-47e9-9ced-a112735805a6",
        "url": "https://www.skims.com/products/cotton-voile-short-marble",
        "name": "COTTON VOILE SHORT | MARBLE",
        "images": [
          {
            "id": "62308793-600d-4355-a7b1-434257163f88",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SKIMS-LOUNGEWEAR-SH-SHO-9475W-MBL-FLT.jpg?v=1749239377",
            "width": 2000,
            "height": 2000,
            "position": 1
          },
          {
            "id": "595069e4-1592-4f0b-93df-a078eb74ebd4",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SH-SHO-9475W-MBL-LD-SKIMS-LOUNGEWEAR_0403-SD.jpg?v=1749248158",
            "width": 2000,
            "height": 2000,
            "position": 2
          },
          {
            "id": "319ddd2f-181b-4d4c-af6f-a042989f0130",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SH-SHO-9475W-MBL-LD-SKIMS-LOUNGEWEAR_0376-FR.jpg?v=1749248158",
            "width": 2000,
            "height": 2000,
            "position": 3
          },
          {
            "id": "aa0e3f68-24c0-4fb3-9de6-a682b09e1c2d",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SH-SHO-9475W-MBL-LD-SKIMS-LOUNGEWEAR_0396-SD.jpg?v=1749239377",
            "width": 2000,
            "height": 2000,
            "position": 4
          },
          {
            "id": "0de186b8-d762-4879-8412-9c83e6ac2202",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/64308-D2-4-0036_FINAL_cf3f6d14-c304-4b3a-af40-90616680e5c0.jpg?v=1749502756",
            "width": 2000,
            "height": 2000,
            "position": 5
          }
        ],
        "price": {
          "currency": "USD",
          "current_value": 33,
          "compare_at_value": 48
        },
        "vendor": "skims.com",
        "first_seen_by_catalog": "2025-11-12T05:43:03.361751+00:00",
        "last_updated_by_catalog": "2025-11-12T05:43:03.361751+00:00"
      }
    ],
    "meta": {
      "total_items": 1290,
      "total_pages": 645,
      "current_page": 1,
      "page_size": 2,
      "has_next": true,
      "has_prev": false
    }
  }
  ```
</ResponseExample>