{ "openapi": "3.0.1", "info": { "title": "Sephora Products Scraper", "description": "Scrape Sephora products (US & Canada) by keyword, brand, category, product ID or URL: prices, ratings, badges, variants, ingredients, reviews, Q&A, EAN. Export to JSON, CSV or Excel.", "version": "0.0", "x-build-id": "eZQ4SSIN9XejdgUje" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nice_dev~sephora-products-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nice_dev-sephora-products-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/nice_dev~sephora-products-scraper/runs": { "post": { "operationId": "runs-sync-nice_dev-sephora-products-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/nice_dev~sephora-products-scraper/run-sync": { "post": { "operationId": "run-sync-nice_dev-sephora-products-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": { "startUrls": { "title": "Start URLs", "maxItems": 1000, "type": "array", "description": "sephora.com URLs: search (`/search?keyword=…`), category (`/shop/…`), brand (`/brand/…`) or product pages (`/product/…-P123456`). Filters set on the site are kept, pagination is automatic. A price bound or a sort already in a URL wins over the form's (a warning says so); a price bound the URL lacks is completed by the price fields below. Canada URLs (`/ca/en/…`) switch the country. When this list is not empty, the keyword / brand / category / product ID fields below are ignored; filters, caps, details, reviews and monitoring still apply. Max 1 000 URLs.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "query": { "title": "Search keyword", "maxLength": 200, "type": "string", "description": "Free-text search, exactly as typed in the Sephora search box (e.g. `mascara`, `vitamin c serum`)." }, "searchQueries": { "title": "More search keywords", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several keywords in one run: one search per keyword. Added to **Search keyword**; products found by several searches are saved once.", "default": [], "items": { "type": "string" } }, "brands": { "title": "Brands", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Whole brand catalogues: brand name or the slug of its Sephora page (`lancome` for sephora.com/brand/lancome, `Rare Beauty`, `the-ordinary`). One search per brand.", "default": [], "items": { "type": "string" } }, "categories": { "title": "Categories", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Whole categories: the slug of a Sephora category page (`mascara` for sephora.com/shop/mascara, `face-serum`, `perfume`) or a category id (`cat140006` = Makeup). One search per category. A slug the site does not have (check that sephora.com/shop/ opens) is skipped with a warning.", "default": [], "items": { "type": "string" } }, "productIds": { "title": "Product IDs", "maxItems": 1000, "uniqueItems": true, "type": "array", "description": "Sephora product ids (`P467208`, shown at the end of every product URL). Each one is read from its product page (full details).", "default": [], "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "US", "CA" ], "type": "string", "description": "Sephora store to read: United States (prices in USD) or Canada (prices in CAD, Canadian assortment).", "default": "US" }, "language": { "title": "Language", "enum": [ "en", "fr" ], "type": "string", "description": "Language of names, descriptions and reviews (French: only the reviews written in French; questions are always all of them, in the language they were written in). French is only available with **Country** = Canada.", "default": "en" }, "maxItems": { "title": "Max products", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of products to save for the whole run (after deduplication and filters). 0 = no limit.", "default": 100 }, "maxItemsPerQuery": { "title": "Max products per search", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Cap for EACH search (keyword, brand, category or URL), so that the first search cannot use up the whole **Max products** budget. 0 = no per-search cap.", "default": 0 }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "bestSelling", "topRated", "priceLowToHigh", "priceHighToLow" ], "type": "string", "description": "Order of the results, as on the site. Combined with the caps above it decides WHICH products you get (e.g. the 50 best sellers).", "default": "relevance" }, "extractDetails": { "title": "Extract product details", "type": "boolean", "description": "Open each product page (1 extra request per product) for every shade / size with its own price, sale price and stock status, full description, ingredients, how to use, highlights (clean, vegan…), all photos and videos, loves count, category path and Sephora's AI review summary. Charged per product (see Pricing). Off = search-card fields only.", "default": false }, "includeReviewStats": { "title": "Add rating histogram and barcodes (EAN)", "type": "boolean", "description": "Add the number of reviews per star (1-5), the number of reviewers who recommend the product and the product barcodes (EAN / GTIN) — 1 light extra request per product. Charged per product (see Pricing). Included when **Include reviews** is on.", "default": false }, "includeReviews": { "title": "Include reviews", "type": "boolean", "description": "Add the customer reviews of each product: rating, title, text, date, recommended or not, helpful votes, photos, brand reply, verified / incentivized / staff flags and the reviewer profile (skin type, skin tone, eye and hair color, skin concerns, age range). Charged per review (see Pricing).", "default": false }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Reviews to add per product (100 per request). 0 = all of them, up to about 9,000 reviews per product with 1 GB of memory or more, about 4,000 at the default 512 MB: a dataset row holds at most 7 MB, and the Actor fits it to the run's memory.", "default": 20 }, "reviewsSort": { "title": "Reviews order", "enum": [ "newest", "oldest", "mostHelpful", "highestRating", "lowestRating" ], "type": "string", "description": "Which reviews come first (and therefore which ones you get under the cap above).", "default": "newest" }, "reviewsPostedAfter": { "title": "Reviews posted after", "type": "string", "description": "Only reviews submitted on or after this date: `2026-09-01`, or a period before now such as `7 days`, `1 month`. With **Newest first** the Actor stops reading a product's reviews at the first older one." }, "reviewsMinRating": { "title": "Reviews: min stars", "minimum": 1, "maximum": 5, "type": "integer", "description": "Only reviews with at least this many stars (1-5). Empty = all." }, "reviewsMaxRating": { "title": "Reviews: max stars", "minimum": 1, "maximum": 5, "type": "integer", "description": "Only reviews with at most this many stars (1-5), e.g. 2 for the negative reviews. Empty = all." }, "includeQuestions": { "title": "Include questions & answers", "type": "boolean", "description": "Add the customer questions of each product with their answers (brand answers flagged), all languages, each as written. Charged per question (see Pricing).", "default": false }, "maxQuestionsPerProduct": { "title": "Max questions per product", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Questions to add per product, newest first. 0 = all of them.", "default": 10 }, "minPrice": { "title": "Min price", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Only products with a price at or above this amount (in the store currency). Applied by Sephora. A pasted search URL that already has a minimum price keeps its own." }, "maxPrice": { "title": "Max price", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Only products with a price at or below this amount (in the store currency). Applied by Sephora. A pasted search URL that already has a maximum price keeps its own." }, "minRating": { "title": "Min rating", "enum": [ "", "1", "2", "3", "4" ], "type": "string", "description": "Only products rated at least this many stars. Applied by Sephora.", "default": "" }, "filterBrands": { "title": "Only these brands", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Keep only these brands inside a keyword or category search (brand name as shown on Sephora, e.g. `Lancôme`, `Rare Beauty`). Applied by Sephora.", "default": [], "items": { "type": "string" } }, "newArrivalsOnly": { "title": "New arrivals only", "type": "boolean", "description": "Only the products Sephora marks as new. Applied by Sephora.", "default": false }, "refinements": { "title": "Other site filters", "maxItems": 30, "uniqueItems": true, "type": "array", "description": "Any other filter of the Sephora sidebar, as the site writes it in the URL after `ref=`: `filters[ingredientPreferences]=crueltyFree`, `filters[SkinType]=oily`, `filters[benefits]=longWearing`, `filters[Pickup]=`, `filters[SameDay]=`. A filter the site does not know stops the run with a clear message instead of silently returning nothing.", "default": [], "items": { "type": "string" } }, "saleOnly": { "title": "On sale only", "type": "boolean", "description": "Only products currently on sale.", "default": false }, "exclusiveOnly": { "title": "Sephora exclusives only", "type": "boolean", "description": "Only products sold exclusively at Sephora.", "default": false }, "bestsellersOnly": { "title": "Best sellers only", "type": "boolean", "description": "Only products flagged as best sellers. Sephora shows that badge on search results only: a product given by ID or URL has none and is kept.", "default": false }, "inStockOnly": { "title": "In stock only", "type": "boolean", "description": "Drop the products whose every shade / size is out of stock. Needs **Extract product details** (stock is only on the product page); ignored otherwise.", "default": false }, "excludeKeywords": { "title": "Exclude keywords", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Drop the products whose name or brand contains one of these words (case and accents ignored).", "default": [], "items": { "type": "string" } }, "onlyNew": { "title": "Only new products", "type": "boolean", "description": "Skip the products that a previous run (same **Memory key**) already delivered: they are not saved and not charged, and their page is not even opened. First run = everything is new.", "default": false }, "stateKey": { "title": "Memory key", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "maxLength": 64, "type": "string", "description": "Name of the memory used by **Only new products**. Give each schedule / task its own key (e.g. `new-skincare`) so that they do not share their memory. Letters, digits, `-` and `_`.", "default": "default" }, "resetState": { "title": "Reset the memory", "type": "boolean", "description": "Forget everything remembered under this **Memory key** before the run: this run returns (and charges) every product again. Untick it afterwards.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy or your own proxies. Keep the default: it is included in the price. The residential Apify proxy is not available in this Actor.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum number of requests processed in parallel.", "default": 8 }, "maxRequestsPerMinute": { "title": "Max requests per minute", "minimum": 10, "maximum": 2000, "type": "integer", "description": "Most requests to the site in any 60 seconds, all of them counted: search pages, product pages, reviews and questions. A budget, not an even pace: up to this many can leave at once when the minute starts (spread them with the minimum delay below). Lower it if the site answers HTTP 429 / 403 in the log.", "default": 120 }, "minRequestIntervalMs": { "title": "Min delay between requests", "minimum": 0, "maximum": 60000, "type": "integer", "description": "Smallest gap between two requests, in milliseconds. Unlike the per-minute rate, this spreads the requests evenly instead of letting them go out in a burst. 0 = no gap.", "default": 0 }, "maxRequestRetries": { "title": "Max request retries", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries per request before it is marked as failed. Behind a proxy, a request the site turns away is also retried on a new proxy session up to 10 times without using up these retries.", "default": 5 }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Include debug messages in the run log.", "default": false } } }, "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 } } } } } } } } } }