Get Product Listings

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

POST /v1/listings

cURL

PowerShell

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",
    ]
  }'

Success Response

{
  "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
  }
}

When to use: Browse all products from a vendor or filter by specific collections. Use with POST /v1/collections to discover available collections first.

Request

x-api-key · string · required

Your API key for authentication

vendor · string · required

The vendor/brand name to filter by

page · number

Page number for pagination (minimum: 1)

page_size · number

Number of collection products per page (minimum: 1, maximum: 100, default: 10)

collection_urls · string[]

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.

Response

listings · array

Array of listing objects

Show Listing Object

id · string

Unique identifier for the listing

url · string

Product URL

name · string

Product name

images · array

Array of product images

price · object

Product price information

vendor · string

Vendor/brand name

first_seen_by_catalog · string

ISO 8601 timestamp when the product was first discovered by Catalog

last_updated_by_catalog · string

ISO 8601 timestamp when the product was last updated by Catalog

meta · object

Pagination metadata

Show Meta Object

total_items · number

Total number of listings matching the query

total_pages · number

Total number of pages available

current_page · number

Current page number

page_size · number

Number of items per page

has_next · boolean

Whether there is a next page

has_prev · boolean

Whether there is a previous page

cURL

PowerShell

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",
    ]
  }'

Success Response

{
  "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
  }
}