{ "openapi": "3.0.1", "info": { "title": "Sephora Scraper - Products, SKUs, Reviews & 21+ Stores", "description": "From $1/1K. Scrape Sephora products across 21+ storefronts (US, AU, NZ, SG, MY, ID, TH, PH, MX, DE, RO, SE, GR, DK) with a unified schema. Extract brand, title, ingredients, claims, full SKU and shade variants, ratings histogram, top reviews, Q&A, and rich media.", "version": "1.0", "x-build-id": "fRXW5wZ3oHYbSCNxC" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/abotapi~sephora-product-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-abotapi-sephora-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/abotapi~sephora-product-scraper/runs": { "post": { "operationId": "runs-sync-abotapi-sephora-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/abotapi~sephora-product-scraper/run-sync": { "post": { "operationId": "run-sync-abotapi-sephora-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", "required": [ "mode" ], "properties": { "mode": { "title": "Input mode", "enum": [ "search", "url" ], "type": "string", "description": "Search mode = pick storefront + queries. URL mode = paste Sephora product, category, brand, or search URLs. Result filters (price, rating, brand, new arrivals, exclusives) work in both modes.", "default": "search" }, "storefront": { "title": "Storefront", "enum": [ "us", "com.au", "nz", "sg", "my", "id", "th", "ph", "mx", "de", "ro", "se", "gr", "dk" ], "type": "string", "description": "Which Sephora regional site to scrape.", "default": "us" }, "market": { "title": "Market (alias)", "type": "string", "description": "Alias for the storefront in the style of other Sephora scrapers: us, eu-de, eu-ro, eu-gr, mena-ae, mena-sa, mena-qa, mena-kw, sea-au, sea-nz, sea-sg, sea-my, sea-id, sea-th, sea-ph. An explicit market wins over the default Storefront (us); if a non-default Storefront is also set, the Storefront wins and the run logs a warning. Markets without a verified storefront (uk, in, sea-hk, sea-tw, sea-bn, eu-cz, mena-bh, mena-om) are NOT supported: the run logs a warning and falls back to the Storefront value." }, "locale": { "title": "Locale (alias)", "type": "string", "description": "Accepted for compatibility with other Sephora scrapers (e.g. en-AU). The storefront decides the locale; a mismatch logs a warning." }, "categoryIds": { "title": "Category IDs (alias)", "type": "array", "description": "Alias that is merged into Categories (slugs or paths).", "items": { "type": "string" } }, "newProductsPageLimit": { "title": "New products page limit (alias)", "minimum": 0, "type": "integer", "description": "With Only new arrivals on, caps the result pages walked per query (same as Max pages)." }, "maxRequestsPerCrawl": { "title": "Max requests per crawl (alias)", "minimum": 0, "type": "integer", "description": "Caps the result pages walked per query (same as Max pages)." }, "queries": { "title": "Search queries", "type": "array", "description": "Keywords to search the storefront (e.g. 'foundation', 'rare beauty', 'lipstick'). Each query runs as a separate search.", "items": { "type": "string" } }, "categories": { "title": "Category slugs", "type": "array", "description": "Category slugs from the navigation tree (e.g. 'shop/foundation-makeup', 'shop/skincare', 'shop/fragrance'). Optional, leave empty if you only want keyword search.", "items": { "type": "string" } }, "sortBy": { "title": "Sort order", "enum": [ "relevance", "popular", "rating", "price-asc", "price-desc", "newest" ], "type": "string", "description": "How to order the search results.", "default": "relevance" }, "specialsOnly": { "title": "Specials (Sale) only", "type": "boolean", "description": "Scrape Sephora's 'Sale' collection instead of your queries/categories. Covers the SEA storefronts only (AU/NZ/SG/MY/ID/TH/PH); ignored elsewhere. The Sale collection does not combine with keywords or categories, so when this is on, 'Search queries' and 'Category slugs' are ignored and the full Sale collection is scraped instead.", "default": false }, "urls": { "title": "Sephora URLs", "type": "array", "description": "One or more full Sephora URLs (product, category, brand, or search). The scraper auto-detects the storefront from the host. Left untouched, one example per URL shape is scraped. `startUrls` is accepted as an alias.", "items": { "type": "string" }, "default": [ "https://www.sephora.com/search?keyword=foundation", "https://www.sephora.com/search?keyword=mascara" ] }, "brands": { "title": "Filter by brand (optional)", "type": "array", "description": "Brand slugs to filter results (e.g. 'rare-beauty', 'fenty-beauty', 'charlotte-tilbury'). Multiple allowed.", "items": { "type": "string" } }, "priceMin": { "title": "Minimum price", "minimum": 0, "type": "integer", "description": "Minimum product price in the storefront's currency." }, "priceMax": { "title": "Maximum price", "minimum": 0, "type": "integer", "description": "Maximum product price in the storefront's currency." }, "ratingMin": { "title": "Minimum rating", "minimum": 0, "maximum": 5, "type": "integer", "description": "Only return products with average rating at or above this value. Use 0 (no filter), 3, 4, or 5.", "default": 0 }, "newOnly": { "title": "New arrivals only", "type": "boolean", "description": "Return only products marked as new arrivals on the storefront.", "default": false }, "onlyNewProducts": { "title": "New arrivals only (alias)", "type": "boolean", "description": "Alias of 'New arrivals only'. Either one switches the filter on.", "default": false }, "exclusiveOnly": { "title": "Sephora exclusives only", "type": "boolean", "description": "Return only products marked 'Only at Sephora'.", "default": false }, "fetchDetails": { "title": "Fetch product details", "type": "boolean", "description": "Fetch the product detail page for full content. Required for ingredients, howToUse, full variant list, claims, awards, ratings histogram. SERP-only mode is faster and cheaper.", "default": false }, "fetchReviews": { "title": "Fetch top reviews", "type": "boolean", "description": "Pull the top N reviews per product (sorted by helpfulness). Adds one extra fetch per product.", "default": false }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 1, "maximum": 100, "type": "integer", "description": "Cap the number of reviews per product (1-100). Ignored unless 'Fetch top reviews' is on.", "default": 10 }, "fetchQna": { "title": "Fetch top Q&A", "type": "boolean", "description": "Pull questions and answers per product (sorted by recency). Adds one extra fetch per product.", "default": false }, "maxQnaPerProduct": { "title": "Max Q&A per product", "minimum": 1, "maximum": 50, "type": "integer", "description": "Cap the number of Q&A entries per product (1-50). Ignored unless 'Fetch top Q&A' is on.", "default": 5 }, "maxPages": { "title": "Max pages per query", "minimum": 0, "type": "integer", "description": "Optional bound on result pages walked per query/category/URL. Leave empty to walk every result page; the walk stops when the storefront returns no next page, a repeat page is detected, or 'Max products total' is hit." }, "maxProducts": { "title": "Max products total", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Total cap across all queries/URLs. Set to 0 for the hard maximum of 100000 (also bounded by maxPages and the storefront's own result count).", "default": 20 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Residential proxy is required for the US storefront. AU/NZ/EU storefronts also work better with a residential proxy in the matching country. Default uses Apify's built-in proxy. Free plan: does not include residential, default proxy may return zero results on the US storefront.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }, "resumeFromCheckpoint": { "title": "Resume from checkpoint", "type": "boolean", "description": "Resume a previous run from the last saved checkpoint.", "default": true }, "resumeFromRunId": { "title": "Resume from run ID", "type": "string", "description": "Optional: paste a previous run ID (or dataset ID) from this actor. Products already collected there are skipped, so this run only returns new ones. Leave empty for a normal run. For recurring daily/weekly monitoring of the same search or URLs, use Incremental mode below instead." }, "incrementalMode": { "title": "Incremental changes for scheduled runs", "type": "boolean", "description": "Turn this on for daily or recurring monitoring of the same search/category/URLs. The first run returns all matching products as NEW. Later runs normally return only NEW, UPDATED, and REAPPEARED products. UPDATED means a compared field changed: price, was price, specials, stock, variants, title, brand, categories, images, descriptions and every other product field. Review and rating counters (rating, reviewCount, stats ratings/loves/question counts, ratingHistogram, topReviews, topQuestions, sentiments) and scrapedAt are kept in the output but never trigger UPDATED; add more with \"Ignore fields when detecting changes\". Turn on \"Emit unchanged\" or \"Emit expired\" only when you also want those products returned (and billed). State is kept separately per search/category/URL and filter setup; use State key when you want to name or deliberately share a monitoring campaign. To continue one specific interrupted run instead, use Resume from run ID above.", "default": false }, "stateKey": { "title": "State key (optional, incremental mode only)", "type": "string", "description": "Optional. Name this monitoring campaign to keep its state stable, or to deliberately share state across differently-configured runs. Leave empty to let the actor derive a key automatically from the storefront/search/category/URL and filter settings -- different setups then never mix state with each other." }, "emitUnchanged": { "title": "Emit unchanged products (incremental mode only)", "type": "boolean", "description": "Off by default. Turn on to also return products that have not changed since the last run, marked UNCHANGED. This returns -- and bills -- extra rows you already have, so leave it off unless you specifically want the full snapshot every run.", "default": false }, "emitExpired": { "title": "Emit expired products (incremental mode only)", "type": "boolean", "description": "Off by default. Turn on to also return products that were present in a previous run but are no longer found, marked EXPIRED. Only produced once a run has fully scanned the tracked search/category/URLs -- not when Max products capped it or when Resume was used. This returns -- and bills -- extra synthetic rows, so leave it off unless you need expiry tracking.", "default": false }, "ignoreFieldsForChanges": { "title": "Ignore fields when detecting changes (incremental mode only)", "type": "array", "description": "Optional. Field names to exclude from UPDATED change detection, in addition to the built-in handling (review and rating counters never trigger a false UPDATED). Use a top-level name such as \"badges\", or a dotted path for a nested key such as \"stats.lovesCount\". Ignored fields stay in the output; they are only left out of the comparison and of changedFields.", "items": { "type": "string" } }, "mcpConnectors": { "title": "Pipe results into your apps (optional)", "type": "array", "description": "Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify → Settings → Integrations, then select it here. The connector receives a condensed, human-readable summary per item (title + key fields), not the full JSON — the complete record stays in the dataset. Leave empty to skip. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com)." }, "notionParentPageUrl": { "title": "Notion parent page (Notion connector only)", "type": "string", "description": "URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors." }, "maxNotifyListings": { "title": "Max items to export per connector", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on items written to each connector per run. Does not affect the dataset.", "default": 50 } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }