# Ulta Product Scraper (`sian.agency/ulta-product-scraper`) Actor

Scrape Ulta Beauty products — brand, price, ratings, images, ingredients & shade variants. Browse any category, full detail enrichment, clean JSON/CSV, no code.

- **URL**: https://apify.com/sian.agency/ulta-product-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** E-commerce, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.30 / 1,000 overview products

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Ulta Product Scraper — Brand, Prices, Ratings & Ingredients 💄

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Home Depot Product Scraper](https://img.shields.io/badge/Store-Home%20Depot%20Product%20Scraper-F96302)](https://apify.com/sian.agency/home-depot-product-scraper?fpr=sian) [![Google Shopping Price Scraper](https://img.shields.io/badge/Store-Google%20Shopping%20Price%20Scraper-4285F4)](https://apify.com/sian.agency/google-shopping-price-scraper?fpr=sian) [![Walmart Product Scraper](https://img.shields.io/badge/Store-Walmart%20Product%20Scraper-0071CE)](https://apify.com/sian.agency/walmart-data-scraper?fpr=sian)

#### 🎉 Pull Ulta Beauty prices, promotions, ratings, ingredients, and shade variants — by category, no code
##### Built for beauty analysts, e-commerce sellers, and brands who need fresh Ulta product data on demand

---

### 📋 Overview

**Track every price, promotion, rating, and ingredient list on Ulta Beauty — without writing a single line of code.** This scraper turns any Ulta category into a clean, structured spreadsheet of products, complete with brand, prices, ratings, images, shade/size variants, and full ingredient lists.

**Why beauty professionals choose us:**
- ✅ **Complete product data**: 25+ fields per product — brand, price, list/sale price, rating, review count, badges, variants, and more
- ⚡ **Fast category mode**: pull 64 products per page in seconds; scale to thousands across multiple categories
- 🎨 **Shade & size variants**: capture every color/size option with its own price (Detail mode)
- 💰 **Pay only for results**: charged per product you actually receive — no wasted spend, free tier to test
- 💎 **Detail enrichment**: add the full description, ingredients list, and how-to-use directions with one switch
- ✨ **NEW**: browse any category, sort by best-sellers, top-rated, newest, or price — just like the Ulta site

---

### ✨ Features

- 🗂️ **Category Browsing**: scrape any Ulta category page (makeup, skincare, hair, fragrance, tools…)
- 🏷️ **Full Pricing**: current price, list price, sale price, kit price, discount, and promo flags
- ⭐ **Ratings & Reviews**: star rating and total review count for every product
- ™️ **Brand Data**: the beauty brand behind every product, ready for brand-level analysis
- 🎨 **Shade & Size Variants**: every variant with its own SKU, name, and price (Detail mode)
- 🧪 **Ingredients & Directions**: full ingredient list and how-to-use text (Detail mode)
- 🖼️ **Product Images**: product image URLs, ready for catalogs or feeds
- 🧭 **Breadcrumbs & Categories**: the product's full category path for clean classification
- 🎛️ **Native Filters**: narrow any category by brand, color, benefit, or price using Ulta's own filters
- 📦 **Clean Export**: results delivered as structured JSON or CSV, ready for Excel or your database
- 🚀 **No-Code Setup**: configure categories in a simple form — no scripts, no maintenance

---

### 🎬 Quick Start

Paste one or more Ulta category paths, pick a mode, and run. In under a minute you'll have a structured dataset of Ulta products you can download as JSON or CSV. No setup, no code.

```bash
curl -X POST https://api.apify.com/v2/acts/sian.agency~ulta-product-scraper/runs?token=YOUR_TOKEN \
-H 'Content-Type: application/json' \
-d '{"categories": ["/shop/makeup/eyes/mascara"], "scrapeMode": "overview"}'
````

***

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Add Your Categories

Paste one or more Ulta category paths (e.g. `/shop/makeup/eyes/mascara`, `/shop/skincare/moisturizers`) — one per line. Copy the path straight from any Ulta browse-page URL.

#### Step 2: Choose Your Mode

Pick **Overview** for fast category results, or **Detail** to also pull the full description, ingredients list, and every shade/size variant.

#### Step 3: Run & Download

Click **Start**, then export your results as JSON, CSV, or Excel from the Apify dataset.

**That's it! In just a few minutes, you'll have:**

- A clean table of Ulta products with brand, prices, and promotions
- Ratings, review counts, and product images
- Full ingredients and shade variants (Detail mode)

***

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| categories | array | No | Ulta category paths, one per item (e.g. `/shop/makeup/eyes/mascara`) |
| scrapeMode | string | No | `overview` (fast category) or `detail` (adds description + ingredients + variants) |
| sort | string | No | `best_sellers`, `top_rated`, `new_arrivals`, `price_low`, or `price_high` |
| gnFilters | array | No | Advanced — Ulta facet filters from a filtered category URL (e.g. `BENEFIT--WATERPROOF`) |
| productUrls | array | No | Detail mode only — specific Ulta product URLs to scrape directly |
| maxResults | integer | No | Maximum products to return across all categories |

**Example — fast category browse:**

```json
{
  "categories": ["/shop/makeup/eyes/mascara", "/shop/skincare/moisturizers"],
  "scrapeMode": "overview",
  "sort": "best_sellers",
  "maxResults": 100
}
```

**Example — full detail with ingredients & variants:**

```json
{
  "categories": ["/shop/makeup/face/foundation"],
  "scrapeMode": "detail",
  "sort": "top_rated",
  "maxResults": 50
}
```

***

### 📤 Output

Results are saved to the Apify dataset with **25+ fields per product**, including:

| Field | Type | Description |
|-------|------|-------------|
| productTitle | string | Product name |
| brand | string | Beauty brand |
| variant\_label | string | Shade/size variant label |
| price | number | Current price |
| list\_price | number | Regular list price |
| sale\_price | number | Sale price when on offer |
| on\_sale | boolean | Whether the product is on sale |
| rating | number | Average star rating |
| review\_count | number | Total number of reviews |
| badge | string | Merchandising badge (e.g. "New", "Best Seller") |
| in\_stock | boolean | Whether the product is in stock |
| images | array | Product image URLs |
| breadcrumbs | array | Full category path (Detail mode) |
| description | string | Full product description (Detail mode) |
| ingredients | string | Ingredients list (Detail mode) |
| usage | string | How-to-use directions (Detail mode) |
| variants | array | Shade/size variants with SKU, name, and price (Detail mode) |

**Example:**

```json
{
  "sku_id": "2596644",
  "productTitle": "Tartelette Tubing Mascara",
  "brand": "Tarte",
  "variant_label": "6 colors",
  "price": 28.0,
  "list_price": 28.0,
  "on_sale": false,
  "rating": 4.1,
  "review_count": 1850,
  "badge": null,
  "in_stock": true,
  "images": ["https://media.ultainc.com/i/ulta/2596644"],
  "breadcrumbs": ["Makeup", "Eyes", "Mascara"],
  "ingredients": "Water, Synthetic Beeswax, Copernicia Cerifera (Carnauba) Wax...",
  "variants": [{ "sku_id": "2596644", "name": "Black", "list_price": 28.0 }]
}
```

***

### 💼 Use Cases & Examples

#### 1. Price Monitoring

**Retailers and resellers tracking Ulta prices over time to stay competitive.**

**Input:** Your category paths and a daily schedule
**Output:** Current price, list price, sale price, and promo flags for every match
**Use:** Spot price drops, react to promotions, and keep your own pricing sharp.

#### 2. Competitive Analysis

**Beauty brands and category managers benchmarking against the Ulta assortment.**

**Input:** Category paths sorted by best-sellers
**Output:** Competitor prices, ratings, review counts, and promotion activity
**Use:** Understand where you win or lose on price, rating, and assortment.

#### 3. Catalog Building

**E-commerce teams building a clean beauty catalog with images, ingredients, and variants.**

**Input:** Category paths, in Detail mode
**Output:** Titles, brands, images, ingredients, descriptions, and full variant lists
**Use:** Populate your storefront or PIM with structured, ready-to-use product data.

#### 4. Ingredient & Formulation Research

**Product developers and clean-beauty analysts studying what's in best-selling products.**

**Input:** Category paths in Detail mode
**Output:** Full ingredient lists and how-to-use directions per product
**Use:** Track formulation trends and benchmark ingredient claims across brands.

#### 5. Assortment & Trend Research

**Merchandisers studying which products and shades carry the best ratings and reviews.**

**Input:** Category paths sorted by top-rated or new arrivals
**Output:** Rating data, review counts, badges, and variant breadth per product
**Use:** Plan assortment, surface emerging products, and spot trending shades.

#### 6. Market Research & Trend Spotting

**Analysts tracking new launches, best-sellers, and review momentum in beauty.**

**Input:** Broad category paths sorted by newest or top-rated
**Output:** Product launches, rating trends, and review-count growth
**Use:** Surface emerging products and category trends before competitors do.

***

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/ulta-product-scraper').call({
  categories: ['/shop/makeup/eyes/mascara'],
  scrapeMode: 'overview'
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/ulta-product-scraper').call(
    run_input={'categories': ['/shop/makeup/eyes/mascara'], 'scrapeMode': 'overview'}
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item)
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~ulta-product-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"categories": ["/shop/makeup/eyes/mascara"], "scrapeMode": "overview"}'
```

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger**: Schedule (e.g. daily) or webhook
2. **HTTP Request**: Call the actor API with your categories
3. **Process**: Handle the JSON results
4. **Action**: Save to a sheet, sync to a database, or send a price-drop alert

***

### 📊 Performance & Pricing

#### FREE Tier (Try It Now)

- **25 products** per run — full feature access, same data quality
- No credit card required
- Perfect for testing and small projects

#### PAID Tier (Production Ready)

- **Unlimited** products per run
- Browse multiple categories in one go
- Pay-per-result: you're only charged for the products you actually receive

💰 **Best value on the market** — transparent pay-per-result pricing with no hidden subscription fees.

🔗 [View current pricing](https://apify.com/sian.agency/ulta-product-scraper?fpr=sian)

***

### ❓ Frequently Asked Questions

**Q: How many products can I scrape?**
A: FREE tier: 25 products per run. PAID tier: unlimited products across as many categories as you like.

**Q: How do I find the category path?**
A: Open any Ulta category page and copy the part of the URL after `ulta.com` (e.g. `/shop/makeup/eyes/mascara`). A full URL works too.

**Q: What's the difference between Overview and Detail mode?**
A: Overview is the fast path — category results with brand, price, ratings, images, and badges. Detail adds the full description, ingredients list, how-to-use directions, and every shade/size variant.

**Q: Can I scrape specific products instead of a whole category?**
A: Yes — switch to Detail mode and paste the product URLs into the `productUrls` field.

**Q: What output formats are available?**
A: JSON, CSV, and Excel — export directly from the Apify dataset.

**Q: Is this legal?**
A: Yes — we only extract publicly available product data. See the legal section below.

**Q: How fresh is the data?**
A: Every run pulls live data directly from Ulta at the moment you run it. Schedule runs to keep prices and stock up to date.

***

### 🐞 Troubleshooting

**No results returned**

- Check that your category path is valid (copy it straight from an Ulta browse-page URL)
- Try a broader category or a different sort order, then re-run

**Missing ingredients or description**

- Ingredients, descriptions, and variants only appear in **Detail** mode — switch `scrapeMode` to `detail`

**Fewer results than expected on the free tier**

- The FREE tier is capped at 25 products per run — upgrade to PAID for unlimited results

***

### ⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what is publicly shared. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

***

### ⚖️ Trademark Disclaimer

Ulta Beauty® is a trademark of Ulta Beauty, Inc. This actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Ulta Beauty, Inc.

***

### ⭐ Love This Tool?

If this actor saves you time, please [leave us a 5-star review](https://apify.com/sian.agency/ulta-product-scraper/reviews) — it helps other professionals discover it and helps us keep improving.

***

### 🤝 Support

[![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi)

**Join our active support community**

- For issues or questions, open an issue in the actor's repository
- Check the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- 📧 <apify@sian-agency.online>

#### More from SIÁN Agency

- 🪚 [Home Depot Product Scraper](https://apify.com/sian.agency/home-depot-product-scraper?fpr=sian) — Home Depot product data, prices & specs
- 🛍️ [Google Shopping Price Scraper](https://apify.com/sian.agency/google-shopping-price-scraper?fpr=sian) — track offers and price history across the web
- 🏪 [Walmart Product Scraper](https://apify.com/sian.agency/walmart-data-scraper?fpr=sian) — Walmart product and review data

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Actor input Schema

## `categories` (type: `array`):

🗂️ **CATEGORY BROWSING:** The Ulta category pages to scrape — copy the path straight from any Ulta browse page URL.

📝 **EXAMPLES:** `/shop/makeup/eyes/mascara` · `/shop/skincare/moisturizers` · `/shop/hair/shampoo-conditioner` · `/shop/fragrance/women`

🔧 **HOW TO GET IT:** Open any Ulta category page, then copy the part of the URL after `ulta.com` (e.g. `https://www.ulta.com/shop/makeup/eyes/mascara` → paste `/shop/makeup/eyes/mascara`). A full URL works too.

💡 **TIP:** Add one category per line — each runs as its own browse and all results land in the same dataset.

🖊️ **BULK EDIT:** Click "Bulk edit" to paste many categories at once (one per line).

✅ **IMPORTANT:** Provide at least one category (or, in Detail mode, product URLs) so there's something to scrape.

## `scrapeMode` (type: `string`):

⚙️ **SCRAPE DEPTH:** Choose how much data to pull per product.

⚡ **Overview (fast):** Category results only — brand, product name, list/sale price, rating, reviews, image, badges and shade/size variant label. Fastest and cheapest path (64 products per page).

🔬 **Detail (full description):** Everything in Overview PLUS the full product description, ingredients list, how-to-use directions, category breadcrumbs and every shade/size variant scraped from each product page.

💡 **TIP:** Start with Overview to scope your catalog, then switch to Detail when you need descriptions, ingredients or the full variant list.

## `sort` (type: `string`):

🔃 **RESULT ORDERING:** Order category results using Ulta's own native sort options — so you get the same ranking real shoppers see.

🏆 **Best sellers** surfaces the most popular products first · ⭐ **Top rated** leads with the highest-reviewed items · 🆕 **New arrivals** prioritizes the latest launches · 💲 **Price** sorts ascending or descending.

## `gnFilters` (type: `array`):

🎛️ **FACET FILTERING (Advanced):** Narrow a category to a specific segment using Ulta's own filters.

🔧 **HOW TO GET IT:** Apply any filter on an Ulta category page and copy the `gn=` value from the URL (e.g. `?gn=BENEFIT--WATERPROOF` → paste `BENEFIT--WATERPROOF`). Common groups include `BRAND`, `COLOR_EYES`, `BENEFIT`, `PRICE`, `PREFERENCE`.

💡 **TIP:** Leave empty to scrape the full category. Add multiple filters (one per line) to stack them.

🖊️ **BULK EDIT:** Add one filter per line.

## `productUrls` (type: `array`):

🔗 **DIRECT PRODUCT ENRICHMENT (Detail mode only):** Specific Ulta product pages to scrape directly — full description, ingredients, directions and variants.

📝 **EXAMPLE:** `https://www.ulta.com/p/tartelette-tubing-mascara-pimprod2033171?sku=2596644`

💡 **TIP:** Use this when you already know the exact products you want — no category browse needed. Requires Scrape Mode = Detail.

🖊️ **BULK EDIT:** Add one product URL per line.

## `maxResults` (type: `integer`):

🔢 **RESULT CAP:** Maximum number of products to return across all categories combined.

🎁 **TIER-BASED LIMITS:**

- **FREE users:** Up to 25 products per run
- **PAID users:** Unlimited — scrape entire categories in a single run

💡 **TIP:** Keep this low while you dial in your categories, then raise it once the output looks right.

## Actor input object example

```json
{
  "categories": [
    "/shop/makeup/eyes/mascara"
  ],
  "scrapeMode": "overview",
  "sort": "best_sellers",
  "maxResults": 100
}
```

# Actor output Schema

## `ultaProducts` (type: `string`):

Scraped Ulta products with brand, prices, promotions, ratings, images, ingredients and variants.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "categories": [
        "/shop/makeup/eyes/mascara"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/ulta-product-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "categories": ["/shop/makeup/eyes/mascara"] }

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/ulta-product-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "categories": [
    "/shop/makeup/eyes/mascara"
  ]
}' |
apify call sian.agency/ulta-product-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=sian.agency/ulta-product-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Ulta Product Scraper",
        "description": "Scrape Ulta Beauty products — brand, price, ratings, images, ingredients & shade variants. Browse any category, full detail enrichment, clean JSON/CSV, no code.",
        "version": "1.0",
        "x-build-id": "P618C6W2gPVFwgdT0"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/sian.agency~ulta-product-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-sian.agency-ulta-product-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/sian.agency~ulta-product-scraper/runs": {
            "post": {
                "operationId": "runs-sync-sian.agency-ulta-product-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/sian.agency~ulta-product-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-sian.agency-ulta-product-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "categories": {
                        "title": "🗂️ Category Paths",
                        "type": "array",
                        "description": "🗂️ **CATEGORY BROWSING:** The Ulta category pages to scrape — copy the path straight from any Ulta browse page URL.\n\n📝 **EXAMPLES:** `/shop/makeup/eyes/mascara` · `/shop/skincare/moisturizers` · `/shop/hair/shampoo-conditioner` · `/shop/fragrance/women`\n\n🔧 **HOW TO GET IT:** Open any Ulta category page, then copy the part of the URL after `ulta.com` (e.g. `https://www.ulta.com/shop/makeup/eyes/mascara` → paste `/shop/makeup/eyes/mascara`). A full URL works too.\n\n💡 **TIP:** Add one category per line — each runs as its own browse and all results land in the same dataset.\n\n🖊️ **BULK EDIT:** Click \"Bulk edit\" to paste many categories at once (one per line).\n\n✅ **IMPORTANT:** Provide at least one category (or, in Detail mode, product URLs) so there's something to scrape.",
                        "default": [
                            "/shop/makeup/eyes/mascara"
                        ],
                        "items": {
                            "type": "string"
                        }
                    },
                    "scrapeMode": {
                        "title": "⚙️ Scrape Mode",
                        "enum": [
                            "overview",
                            "detail"
                        ],
                        "type": "string",
                        "description": "⚙️ **SCRAPE DEPTH:** Choose how much data to pull per product.\n\n⚡ **Overview (fast):** Category results only — brand, product name, list/sale price, rating, reviews, image, badges and shade/size variant label. Fastest and cheapest path (64 products per page).\n\n🔬 **Detail (full description):** Everything in Overview PLUS the full product description, ingredients list, how-to-use directions, category breadcrumbs and every shade/size variant scraped from each product page.\n\n💡 **TIP:** Start with Overview to scope your catalog, then switch to Detail when you need descriptions, ingredients or the full variant list.",
                        "default": "overview"
                    },
                    "sort": {
                        "title": "🔃 Sort Order",
                        "enum": [
                            "best_sellers",
                            "top_rated",
                            "new_arrivals",
                            "price_low",
                            "price_high"
                        ],
                        "type": "string",
                        "description": "🔃 **RESULT ORDERING:** Order category results using Ulta's own native sort options — so you get the same ranking real shoppers see.\n\n🏆 **Best sellers** surfaces the most popular products first · ⭐ **Top rated** leads with the highest-reviewed items · 🆕 **New arrivals** prioritizes the latest launches · 💲 **Price** sorts ascending or descending.",
                        "default": "best_sellers"
                    },
                    "gnFilters": {
                        "title": "🎛️ Category Filters (Advanced)",
                        "type": "array",
                        "description": "🎛️ **FACET FILTERING (Advanced):** Narrow a category to a specific segment using Ulta's own filters.\n\n🔧 **HOW TO GET IT:** Apply any filter on an Ulta category page and copy the `gn=` value from the URL (e.g. `?gn=BENEFIT--WATERPROOF` → paste `BENEFIT--WATERPROOF`). Common groups include `BRAND`, `COLOR_EYES`, `BENEFIT`, `PRICE`, `PREFERENCE`.\n\n💡 **TIP:** Leave empty to scrape the full category. Add multiple filters (one per line) to stack them.\n\n🖊️ **BULK EDIT:** Add one filter per line.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "productUrls": {
                        "title": "🔗 Product URLs (Detail Mode)",
                        "type": "array",
                        "description": "🔗 **DIRECT PRODUCT ENRICHMENT (Detail mode only):** Specific Ulta product pages to scrape directly — full description, ingredients, directions and variants.\n\n📝 **EXAMPLE:** `https://www.ulta.com/p/tartelette-tubing-mascara-pimprod2033171?sku=2596644`\n\n💡 **TIP:** Use this when you already know the exact products you want — no category browse needed. Requires Scrape Mode = Detail.\n\n🖊️ **BULK EDIT:** Add one product URL per line.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxResults": {
                        "title": "🔢 Max Results",
                        "minimum": 1,
                        "type": "integer",
                        "description": "🔢 **RESULT CAP:** Maximum number of products to return across all categories combined.\n\n🎁 **TIER-BASED LIMITS:**\n- **FREE users:** Up to 25 products per run\n- **PAID users:** Unlimited — scrape entire categories in a single run\n\n💡 **TIP:** Keep this low while you dial in your categories, then raise it once the output looks right.",
                        "default": 100
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```