Use Sephora Catalog Price & Rating Finder with Python

Search Sephora's product catalog by keyword, bestsellers, or new arrivals, filtered by rating, brand, and price, with merchandising flags, review counts, and images for every matching product.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "brands": [],
  "categories": [],
  "includeBestsellersOnly": false,
  "includeDetails": false,
  "includeImages": false,
  "includeNewOnly": false,
  "includeQuestions": false,
  "includeReviewStats": false,
  "includeReviews": false,
  "market": "us",
  "maxImagesPerProduct": 3,
  "maxItems": 1,
  "maxItemsPerQuery": 0,
  "maxQuestionsPerProduct": 10,
  "maxReviewsPerProduct": 20,
  "mode": "search",
  "onlyNewProducts": false,
  "productUrls": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "refinements": [],
  "resetState": false,
  "reviewsSort": "mostHelpful",
  "saleOnly": false,
  "searchQueries": [
    "moisturizer"
  ],
  "sortBy": "relevance",
  "stateKey": "default"
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`mode`	string	required	What to fetch: keyword search, category or brand browse, product URLs, bestsellers, new arrivals, sale, reviews or questions.
`searchQueries`	array	optional	Keywords to search (mode=search). Enter one or more terms, e.g. `moisturizer`, `vitamin c serum`.
`categories`	array	optional	Category slugs, `cat...` IDs or Sephora category URLs (mode=category, bestsellers, newArrivals, sale; also a filter in search). Empty browse modes use the six top-level categories.
`brands`	array	optional	Brand names, slugs or Sephora brand URLs (mode=brand; also an optional filter in other listing modes). Example: `Rare Beauty` or `/brand/rare-beauty-by-selena-gomez`.
`productUrls`	array	optional	Sephora product URLs or `P...` IDs (mode=product, reviews, questions). A `?skuId=` in the URL selects that variant.
`market`	string	optional	Storefront and currency: United States (USD), Canada English (CAD) or Canada French (CAD).
`sortBy`	string	optional	Result ordering for listing modes. Bestsellers and sale default to best selling; new arrivals default to newest.
`minRating`	integer	optional	Only include products rated at or above this value (1-5).
`priceMin`	integer	optional	Only include products whose current price is at or above this amount, in the selected market's currency.
`priceMax`	integer	optional	Only include products whose current price is at or below this amount, in the selected market's currency.
`includeNewOnly`	boolean	optional	Only include products Sephora flags as new.
`includeBestsellersOnly`	boolean	optional	Only include products flagged as bestsellers in listing modes. Not available in product-URL mode.
`saleOnly`	boolean	optional	Only include products currently discounted by Sephora.
`refinements`	array	optional	Optional Sephora facet values, e.g. `filters[skinType]=drySk` or `filters[ingredientPreferences]=crueltyFree`. Up to 20.
`includeDetails`	boolean	optional	Fetch descriptions, ingredients, highlights, variants, stock, category path and brand information for every product in listing modes. Product-URL mode always includes details.
`includeImages`	boolean	optional	Copy product images into the run's key-value store so the image links stay publicly accessible.
`maxImagesPerProduct`	integer	optional	Maximum number of product images to keep and rehost for each product.
`includeReviews`	boolean	optional	Add recent or most-helpful review samples to product records, and fetch review samples in reviews mode.
`maxReviewsPerProduct`	integer	optional	Maximum review rows or samples per product.
`reviewsSort`	string	optional	Ordering for review rows and review samples.
`includeReviewStats`	boolean	optional	Add the rating histogram, recommendation counts, review dates and GTIN/UPC/EAN identifiers.
`includeQuestions`	boolean	optional	Add questions with their answers to product records, and fetch question rows in questions mode.
`maxQuestionsPerProduct`	integer	optional	Maximum question rows or embedded questions per product.
`maxItems`	integer	optional	Hard cap on all records emitted by the run.
`maxItemsPerQuery`	integer	optional	Cap records per keyword, category, brand or product URL. 0 means no per-source cap.
`onlyNewProducts`	boolean	optional	Skip product IDs that were already returned under the same state key in earlier runs.
`stateKey`	string	optional	Name for the saved product-ID state used by 'Only new products'.
`resetState`	boolean	optional	Forget previously seen product IDs for this state key before the run.
`proxyConfiguration`	object	optional	Optional. Sephora's public catalog and review endpoints work without a proxy.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/t515auZbFJrdZ5vdU/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Sephora product, review and question records with prices, variants, ingredients, stock, ratings, review statistics and Q&A across US, Canada English and Canada French.

Questions before you run

Which inputs are required?

The published required fields are mode

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build CmWi1inWXx3Khxocm and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.