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

<Tip>
  **When to use:** Browse all products from a vendor or filter by specific collections. Use with [`GET /v2/collections`](/v2/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 query="vendor" type="string" required>
  The vendor/brand name to filter by
</ParamField>

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

<ParamField query="page_size" type="number" optional>
  Number of listings per page (minimum: 1, maximum: 100, default: 20)
</ParamField>

<ParamField query="collection_url" type="string" optional>
  Collection URL to filter by. If provided, only listings from this collection will be returned.

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

## Response

<ResponseField name="data" 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="pagination" type="object">
  Pagination metadata

  <Expandable title="Pagination Object">
    <ResponseField name="page" type="number">
      Current page number
    </ResponseField>

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

    <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="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>

<ResponseField name="meta" type="object">
  Response metadata (currently empty for this endpoint)
</ResponseField>

<RequestExample dropdown>
  ```powershell cURL theme={null}
  curl -X GET "https://api.getcatalog.ai/v2/listings?vendor=skims.com&page=1&page_size=2&collection_url=https://www.skims.com/collections/skims-sale" \
    -H "x-api-key: $CATALOG_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    vendor: 'skims.com',
    page: '1',
    page_size: '2',
    collection_url: 'https://www.skims.com/collections/skims-sale'
  });

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

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

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

  response = requests.get(
      'https://api.getcatalog.ai/v2/listings',
      headers={'x-api-key': 'YOUR_API_KEY'},
      params={
          'vendor': 'skims.com',
          'page': 1,
          'page_size': 2,
          'collection_url': 'https://www.skims.com/collections/skims-sale'
      }
  )

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

<ResponseExample>
  ```json Success Response theme={null}
  {
    "data": [
      {
        "id": "b3fd62fe-56b3-4d24-8bb5-49485d04b4f7",
        "url": "https://www.skims.com/products/cotton-fleece-short-ruby",
        "name": "COTTON FLEECE SHORT | RUBY",
        "images": [
          {
            "id": "f464d0fb-7b79-4f46-8c4a-d9f52e741787",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SKIMS-LOUNGEWEAR-SH-SHO-8419W-RBY-FLT.jpg?v=1746030214",
            "width": 2000,
            "height": 2000,
            "position": 1
          },
          {
            "id": "ae41651e-d41a-4f37-bc1b-99ae1546540f",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SH-SHO-8419W-RBY-JE-SKIMS-LOUNGEWEAR_0001-FR.jpg?v=1746030214",
            "width": 2000,
            "height": 2000,
            "position": 2
          },
          {
            "id": "e19d3350-f474-4105-8ff5-da66503ef707",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SH-SHO-8419W-RBY-JE-SKIMS-LOUNGEWEAR_0029-SD.jpg?v=1746030214",
            "width": 1730,
            "height": 1730,
            "position": 3
          },
          {
            "id": "b03ee465-81fa-46ed-bb8b-54783dfe04a1",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SH-SHO-8419W-RBY-JE-SKIMS-LOUNGEWEAR_0042-SD.jpg?v=1746030214",
            "width": 1794,
            "height": 1795,
            "position": 4
          },
          {
            "id": "bb2a32ff-1f77-4481-9dcd-4b9d87ff6ab4",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SH-SHO-8419W-RBY-JE-SKIMS-LOUNGEWEAR_0015-FR.jpg?v=1746030214",
            "width": 2000,
            "height": 2000,
            "position": 5
          },
          {
            "id": "97496d20-8041-4f60-9c55-b17e6e216cc0",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SKIMS-LOUNGEWEAR-COTTONFLEECE-RUBY-SW-ALT1.jpg?v=1746049310",
            "width": 2000,
            "height": 2000,
            "position": 6
          }
        ],
        "price": {
          "currency": "USD",
          "current_value": 38,
          "compare_at_value": 54
        },
        "vendor": "skims.com",
        "first_seen_by_catalog": "2026-01-09T23:10:52.178561+00:00",
        "last_updated_by_catalog": "2026-01-09T23:51:28.134254+00:00"
      },
      {
        "id": "d481e8f3-8810-498d-856a-3c67f3b72a1e",
        "url": "https://www.skims.com/products/cotton-fleece-short-onyx",
        "name": "COTTON FLEECE SHORT | ONYX",
        "images": [
          {
            "id": "c3284e88-4c53-43fb-869d-711f356102d5",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SKIMS-LOUNGEWEAR-BO-SHO-4498-ONX-2.jpg?v=1735590602",
            "width": 2000,
            "height": 2000,
            "position": 1
          },
          {
            "id": "737c9e6e-afcb-4a64-accc-beba6ca64271",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/BO-SHO-4498-ONX-MC-SKIMS-LOUNGEWEAR_0010-FR_1acc4cee-2077-4508-b140-60fe1ff2de14.jpg?v=1735590602",
            "width": 2000,
            "height": 1997,
            "position": 2
          },
          {
            "id": "ee45e3aa-9a7c-452b-ba5c-897b88eaeb40",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/BO-SHO-4498-ONX-MC-SKIMS-LOUNGEWEAR_0030-FR-2_912bee2a-78e7-45be-ac7d-e80db61b3401.jpg?v=1735590602",
            "width": 2000,
            "height": 2000,
            "position": 3
          },
          {
            "id": "508d9b8e-0247-47b7-9000-1e341adcc864",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/BO-SHO-4498-ONX-MC-SKIMS-LOUNGEWEAR_0036-SD_11550aee-e4cd-4187-a44c-376b4149d9ef.jpg?v=1735590602",
            "width": 1750,
            "height": 1750,
            "position": 4
          },
          {
            "id": "4300e65c-8a6b-4240-97fc-e60414efb212",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/BO-SHO-4498-ONX-MC-SKIMS-LOUNGEWEAR_0021-BK_ed37d0b1-d6f6-4387-9eeb-f65b45c5d078.jpg?v=1735590602",
            "width": 1997,
            "height": 2000,
            "position": 5
          },
          {
            "id": "efa053af-979e-4c93-91d2-72c0d31cf831",
            "url": "https://cdn.shopify.com/s/files/1/0259/5448/4284/files/SKIMS-COTTON_FLEECE-ONX-DET-2.jpg?v=1760122731",
            "width": 2000,
            "height": 2000,
            "position": 6
          }
        ],
        "price": {
          "currency": "USD",
          "current_value": 27,
          "compare_at_value": 54
        },
        "vendor": "skims.com",
        "first_seen_by_catalog": "2026-01-09T23:10:49.895871+00:00",
        "last_updated_by_catalog": "2026-01-09T23:51:28.134254+00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 2,
      "total_items": 1616,
      "total_pages": 808,
      "has_next": true,
      "has_prev": false
    },
    "meta": {}
  }
  ```
</ResponseExample>