Other

Sephora API

Sephora API returns live Sephora data as clean JSON for sephora The primary endpoint, search, returns product results including product id, sku id, name, brand and price.

3 actionsLive JSON1,000 free creditsMCP-ready

Get a free key Open in playground

🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.

Developers reach for it when they need to validate, enrich, classify and normalize operational data without maintaining one-off scraping code or separate API contracts. If you were about to build or fix a Sephora scraper, this API is the maintained alternative — it returns the same data as clean JSON, with the proxies, rotation and anti-bot handling already solved. This page covers the live example, request shape, response shape and available actions: search, price, product_detail. Every request uses the same ReefAPI envelope, one API key and one shared credit pool, so it fits alongside the rest of your data stack.

Live example

Real request and response JSON

Captured from the indexed primary action, search, on Aug 6, 2026, 3:32 PM UTC.

Captured request

{
  "method": "POST",
  "url": "https://api.reefapi.com/sephora/v1/search",
  "headers": {
    "x-api-key": "$REEF_KEY",
    "content-type": "application/json"
  },
  "body": {
    "query": "mascara",
    "max_results": 30
  }
}

Captured response

{
  "ok": true,
  "meta": {
    "api": "sephora",
    "endpoint": "search",
    "mode": "live",
    "latency_ms": 2929.1,
    "record_count": 30,
    "bytes": 101517,
    "cache_hit": false,
    "completeness_pct": 100,
    "stop_reason": "limit_reached",
    "method": "internal_json_api",
    "pagination": {
      "page": 1,
      "per_page": 60,
      "total_results": 181,
      "pages_fetched": 1,
      "returned": 30,
      "has_more": true,
      "next_page": 2
    },
    "filters": {
      "applied": [],
      "note": null
    },
    "sort": "relevance"
  },
  "data": {
    "products": [
      {
        "product_id": "P467208",
        "sku_id": "2417145",
        "name": "[redacted-name]",
        "brand": "Lancôme",
        "url": "https://www.sephora.com/product/lancome-lash-idole-lash-lifting-volumizing-mascara-P467208?skuId=2417145",
        "price": 16,
        "price_max": 30,
        "price_display": "$16.00 - $30.00",
        "currency": "USD",
        "on_sale": false,
        "on_sale_label": null,
        "rating": 4.5014,
        "review_count": 10755,
        "variant_count": 2,
        "image": "https://www.sephora.com/productimages/sku/s2417145-main-zoom.jpg?imwidth=270",
        "images": [
          {
            "url": "[trimmed-depth]",
            "url_250": "[trimmed-depth]",
            "alt": "[trimmed-depth]"
          }
        ],
        "is_sponsored": false,
        "is_new": false,
        "is_bestseller": true,
        "is_limited_edition": false,
        "is_limited_time_offer": false,
        "is_online_only": false,
        "is_sephora_exclusive": false,
        "is_app_exclusive": false,
        "ships_to_home": false,
        "same_day_eligible": false,
        "next_day_eligible": false,
        "store_pickup_eligible": false
      },
      {
        "product_id": "P502484",
        "sku_id": "2606176",
        "name": "[redacted-name]",
        "brand": "Tower 28 Beauty",
        "url": "https://www.sephora.com/product/makewaves-lengthening-curling-clean-mascara-P502484?skuId=2606176",
        "price": 12,
        "price_max": 20,
        "price_display": "$12.00 - $20.00",
        "currency": "USD",
        "on_sale": false,
        "on_sale_label": null,
        "rating": 3.8206,
        "review_count": 2960,
        "variant_count": 2,
        "image": "https://www.sephora.com/productimages/sku/s2606176-main-zoom.jpg?imwidth=270&pb=allure-2022-bestofbeauty-badge",
        "images": [
          {
            "url": "[trimmed-depth]",
            "url_250": "[trimmed-depth]",
            "alt": "[trimmed-depth]"
          }
        ],
        "is_sponsored": false,
        "is_new": false,
        "is_bestseller": true,
        "is_limited_edition": false,
        "is_limited_time_offer": false,
        "is_online_only": false,
        "is_sephora_exclusive": true,
        "is_app_exclusive": false,
        "ships_to_home": false,
        "same_day_eligible": false,
        "next_day_eligible": false,
        "store_pickup_eligible": false
      },
      {
        "product_id": "P431750",
        "sku_id": "2850378",
        "name": "[redacted-name]",
        "brand": "ILIA",
        "url": "https://www.sephora.com/product/limitless-lash-mascara-P431750?skuId=2850378",
        "price": 17,
        "price_max": 29,
        "price_display": "$17.00 - $29.00",
        "currency": "USD",
        "on_sale": false,
        "on_sale_label": null,
        "rating": 4.2088,
        "review_count": 5383,
        "variant_count": 2,
        "image": "https://www.sephora.com/productimages/sku/s2850378-main-zoom.jpg?imwidth=270&pb=clean-at-sephora",
        "images": [
          {
            "url": "[trimmed-depth]",
            "url_250": "[trimmed-depth]",
            "alt": "[trimmed-depth]"
          }
        ],
        "is_sponsored": false,
        "is_new": false,
        "is_bestseller": true,
        "is_limited_edition": false,
        "is_limited_time_offer": false,
        "is_online_only": false,
        "is_sephora_exclusive": false,
        "is_app_exclusive": false,
        "ships_to_home": false,
        "same_day_eligible": false,
        "next_day_eligible": false,
        "store_pickup_eligible": false
      }
    ],
    "search": {
      "keyword": "mascara",
      "total_results": 181,
      "engine": "NLP",
      "categories": [
        {
          "name": "Makeup",
          "category_id": "cat140006",
          "level": 0,
          "product_count": 178
        },
        {
          "name": "[redacted-name]",
          "category_id": "cat3780034",
          "level": 0,
          "product_count": 28
        },
        {
          "name": "Gifts",
          "category_id": "cat60270",
          "level": 0,
          "product_count": 15
        }
      ],
      "related_searches": [
        "concealer",
        "highlighter",
        "lip liner"
      ]
    },
    "facets": [
      {
        "name": "[redacted-name]",
        "type": "checkboxesWithDropDown",
        "values": [
          {
            "label": "[trimmed-depth]",
            "query_fragment": "[trimmed-depth]",
            "status": "[trimmed-depth]"
          },
          {
            "label": "[trimmed-depth]",
            "query_fragment": "[trimmed-depth]",
            "status": "[trimmed-depth]"
          }
        ]
      },
      {
        "name": "[redacted-name]",
        "type": "range",
        "values": [
          {
            "label": "[trimmed-depth]",
            "query_fragment": "[trimmed-depth]",
            "status": "[trimmed-depth]"
          },
          {
            "label": "[trimmed-depth]",
            "query_fragment": "[trimmed-depth]",
            "status": "[trimmed-depth]"
          },
          {
            "label": "[trimmed-depth]",
            "query_fragment": "[trimmed-depth]",
            "status": "[trimmed-depth]"
          }
        ]
      },
      {
        "name": "Brand",
        "type": "checkboxes",
        "values": [
          {
            "label": "[trimmed-depth]",
            "query_fragment": "[trimmed-depth]",
            "status": "[trimmed-depth]"
          },
          {
            "label": "[trimmed-depth]",
            "query_fragment": "[trimmed-depth]",
            "status": "[trimmed-depth]"
          },
          {
            "label": "[trimmed-depth]",
            "query_fragment": "[trimmed-depth]",
            "status": "[trimmed-depth]"
          }
        ]
      }
    ]
  }
}

Actions

What the Sephora API does

Action	Description	Concrete use case	Key params
search	Search the Sephora catalog. Give a `query` ('mascara', 'vitamin c serum', 'dior lipstick', 'rare beauty blush') and get back 60 products per page, each with Sephora's own product id and default SKU id, brand, price (both ends when Sephora quotes a range), sale flag, star rating, review count, how many shades the product has, the image set, and Sephora's own merchandising flags (bestseller, new, limited edition, Sephora exclusive, same-day/pickup eligibility). Narrow by price band, sort by rating, price or newest. The live facet vocabulary Sephora publishes for your query comes back in `facets`, and the category counts and its own related searches come with it.	Ops teams call search to search the Sephora catalog.	query, max_results, page, sort, price_min, ...
price	Re-check ONE shade's price and stock, cheaply. Give it the Sephora SKU id you already hold and it returns the current price, the regular price, whether that shade is in stock and whether Sephora is flagging it as nearly gone — and nothing else: no description, images, ingredients, shade matrix or reviews. Built for refreshing a catalogue you already have rather than discovering products. It reads Sephora's own SKU-scoped route instead of the whole product document, so it costs a fraction of `product_detail` — measured live on ten products in ten categories: 7.9-14.3 KB against 59.9-421.5 KB for a full `product_detail` (5.2x-45.9x), or 32.5-350.5 KB with its reviews switched off (2.9x-38.1x). The saving grows with the shade count, because the product document carries every sibling shade and this one carries yours. `sku_id` is REQUIRED, because Sephora prices and stocks each shade and size separately: a 49-shade foundation had 9 shades sold out while the product was on sale, so a product-level answer would be right about the product and wrong about the shade you are actually selling.	Developer tools call price to get re-check ONE shade's price and stock, cheaply.	sku_id, product_id, url
product_detail	Get one Sephora product in full, by its product id (or its sephora.com URL). One call returns: the complete image gallery; the complete variant matrix — one row per shade/size with Sephora's own SKU id, that variant's price, sale price, in-stock flag, low-stock flag, swatch, image and URL; the specification set Sephora publishes (size, the structured attribute map — coverage, finish, formulation, skin type, skin concerns, ingredient preferences —, the highlight badges with their explanations, the full ingredient list and the how-to-use copy); the brand with its id and page; availability and price range; the star rating with its distribution; and the top customer reviews with their full text, titles, dates, helpfulness votes, reviewer skin-tone/skin-type/eye/age context and photos. It also returns the product's UPC/EAN barcodes, which Sephora's own product API does not publish anywhere.	Validation workflows call product_detail to get one Sephora product in full, by its product id (or its sephora.com URL).	product_id, url, sku_id, include_reviews, reviews_limit, ...

Code samples

Call search from your stack

curl -X POST https://api.reefapi.com/sephora/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"mascara","max_results":30}'

import requests

r = requests.post(
    "https://api.reefapi.com/sephora/v1/search",
    headers={"x-api-key": REEF_KEY},
    json={
  "query": "mascara",
  "max_results": 30
},
)
print(r.json()["data"])

const res = await fetch("https://api.reefapi.com/sephora/v1/search", {
  method: "POST",
  headers: {
    "x-api-key": process.env.REEF_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
  "query": "mascara",
  "max_results": 30
}),
});
const { ok, data, meta, error } = await res.json();

MCP one-liner

Ask your MCP-connected assistant: call reefapi.sephora.search with {"query":"mascara","max_results":30}.

Use cases

Who uses this API and why

Ops teams use Sephora to search the Sephora catalog.
Developer tools use Sephora to get re-check ONE shade's price and stock, cheaply.
Validation workflows use Sephora to get one Sephora product in full, by its product id (or its sephora.com URL).

FAQ

Questions developers ask before integrating

What is the Sephora API?

Sephora API is a ReefAPI endpoint group for sephora It returns live JSON through POST requests under /sephora/v1.

Is the Sephora API free to try?

Yes. ReefAPI starts with 1,000 free credits, no card required. Sephora calls use the same shared credit balance as every other ReefAPI engine.

Do I need a Sephora login or account?

No login to Sephora is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.

How fresh is the Sephora data?

The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.

How many credits does the Sephora API use?

Sephora actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.

Can I call Sephora from an AI assistant or MCP client?

Yes. Connect ReefAPI once through MCP and your assistant can call sephora actions with the same key, credit pool and JSON envelope used by normal REST requests.

Is the Sephora API a Sephora scraper?

It is the managed alternative to a DIY Sephora scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same sephora back as clean JSON.

Why does my Sephora scraper keep getting blocked?

Most Sephora scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked or failed calls are free.

docs / sephora

Sephora

base /sephora/v13 endpoints

post/sephora/v1/search1 credit

Search the Sephora catalog. Give a `query` ('mascara', 'vitamin c serum', 'dior lipstick', 'rare beauty blush') and get back 60 products per page, each with Sephora's own product id and default SKU id, brand, price (both ends when Sephora quotes a range), sale flag, star rating, review count, how many shades the product has, the image set, and Sephora's own merchandising flags (bestseller, new, limited edition, Sephora exclusive, same-day/pickup eligibility). Narrow by price band, sort by rating, price or newest. The live facet vocabulary Sephora publishes for your query comes back in `facets`, and the category counts and its own related searches come with it.

Parameter		Allowed / range	Description
query	required	—	What to search sephora.com for — a category ('mascara', 'vitamin c serum', 'perfume'), a brand ('rare beauty'), a brand + category ('dior lipstick') or a product name. Sephora runs this through its own NLP search, so it is forgiving of phrasing. ⚠ It is forgiving to a fault: Sephora's search NEVER returns zero — a nonsense query still comes back with ~56 loosely-matched products (measured). Read `search.keyword` and judge the rows; do not treat a non-empty response as proof the term matched.
max_results = 60	optional	1–300	How many products to return (1-300). Sephora paginates 60 per page; asking for more fetches the following pages automatically, up to five.
page = 1	optional	1–200	Which result page to start from (1-based, 60 products per page). Page until `meta.pagination.has_more` is false. Sephora repeats a small number of sponsored rows across pages; those are de-duplicated by `product_id` before you see them.
sort	optional	relevance · top_rated · price_low · price_high · newest	Result ordering, using Sephora's own sort tokens. Only the five listed here were MEASURED to change the ordering — Sephora's code also defines BEST_SELLING, EXCLUSIVE and BRAND_NAME, and all three return the identical default order on this endpoint, so they are deliberately not offered rather than accepted and ignored. An unknown value is rejected, not silently dropped (Sephora itself silently ignores it).
price_min	optional	0–100000	Only products priced at or above this, in US dollars. This is Sephora's own `pl`/`ph` filter and it is the ONE filter this endpoint applies at all. ⚠ It NARROWS hard but it is not a strict predicate: 'foundation' goes 191 → 39 with price_max=25, and 8 of those 39 are priced entirely above $25 (verified variant-by-variant — they do not have a cheaper size). Those rows are passed through rather than dropped, and `meta.filters.applied[].rows_outside_band` counts them for the call you actually made.
price_max	optional	0–100000	Only products priced at or below this, in US dollars. Sephora prices a multi-shade product as a RANGE ('$16.00 - $25.00'); the filter is Sephora's own and it decides how a range is matched, not us. Same caveat as `price_min`: it narrows hard but lets some out-of-band rows through, and `meta.filters` counts them.
brand	optional	—	Keep only products from this brand, matched against the `brand` on each row (case-insensitive, exact then 'contains'). ⚠ HONEST NOTE: this is applied BY THIS ENGINE to the pages it fetched, not by Sephora. Sephora publishes a Brand facet on this endpoint and then ignores it — every brand value returns the identical unfiltered 191 results (measured, both bracket spellings, with and without its NLP engine). So `meta.pagination.total_results` stays Sephora's unfiltered number and `meta.filters` reports exactly what was dropped and by whom. The live brand vocabulary for your query is in `facets`.

Try in playground →

post/sephora/v1/price2 credits

Re-check ONE shade's price and stock, cheaply. Give it the Sephora SKU id you already hold and it returns the current price, the regular price, whether that shade is in stock and whether Sephora is flagging it as nearly gone — and nothing else: no description, images, ingredients, shade matrix or reviews. Built for refreshing a catalogue you already have rather than discovering products. It reads Sephora's own SKU-scoped route instead of the whole product document, so it costs a fraction of `product_detail` — measured live on ten products in ten categories: 7.9-14.3 KB against 59.9-421.5 KB for a full `product_detail` (5.2x-45.9x), or 32.5-350.5 KB with its reviews switched off (2.9x-38.1x). The saving grows with the shade count, because the product document carries every sibling shade and this one carries yours. `sku_id` is REQUIRED, because Sephora prices and stocks each shade and size separately: a 49-shade foundation had 9 shades sold out while the product was on sale, so a product-level answer would be right about the product and wrong about the shade you are actually selling.

Parameter		Allowed / range	Description
sku_id	optional	—	REQUIRED. Sephora's own SKU id for the ONE shade or size you want re-priced — digits only, exactly as `search` and `product_detail` publish it (`2837375`). It is required, not optional, because Sephora prices and stocks every shade and size separately: the same lipstick can be on sale in one shade and sold out in the next, so there is no single product-level answer to give you. A SKU Sephora does not have returns NOT_FOUND. You may pass a sephora.com product URL carrying `?skuId=…` here or in `url` instead.
product_id	optional	—	Optional, and it is a SAFETY CHECK rather than a lookup key: pass the product id you have stored against this SKU and the call fails with NOT_FOUND if Sephora says the SKU belongs to a different product. That is how you find out your catalogue has drifted, instead of quietly writing another product's price into it. Omit it and you simply get Sephora's product id for the SKU back in the response.
url	optional	—	A sephora.com product URL carrying `?skuId=…` — an alternative to `sku_id`. A URL without a `skuId` cannot be priced, because it names a product rather than a purchasable shade.

Try in playground →

post/sephora/v1/product_detail2 credits

Get one Sephora product in full, by its product id (or its sephora.com URL). One call returns: the complete image gallery; the complete variant matrix — one row per shade/size with Sephora's own SKU id, that variant's price, sale price, in-stock flag, low-stock flag, swatch, image and URL; the specification set Sephora publishes (size, the structured attribute map — coverage, finish, formulation, skin type, skin concerns, ingredient preferences —, the highlight badges with their explanations, the full ingredient list and the how-to-use copy); the brand with its id and page; availability and price range; the star rating with its distribution; and the top customer reviews with their full text, titles, dates, helpfulness votes, reviewer skin-tone/skin-type/eye/age context and photos. It also returns the product's UPC/EAN barcodes, which Sephora's own product API does not publish anywhere.

Parameter		Allowed / range	Description
product_id	required	—	Sephora's own product id — the `P…` code at the end of every sephora.com/product/… URL and the `product_id` on every `search` row. A 'P' followed by 5-9 digits (`P427418`, and 8-digit ones like `P87985432` are real). Always a string, taken verbatim; never hashed, composed or re-derived. You may pass the full product URL in `url` instead of this.
url	optional	—	A full sephora.com product URL — an alternative to `product_id`. A `?skuId=` on the URL is honoured and selects that shade as `selected_variant`.
sku_id	optional	—	Which shade/size to return as `selected_variant`. Sephora's own SKU id, exactly as `search` and the variant rows publish it (digits only). Omit to get the SKU Sephora shows by default. Every variant comes back either way — this only moves the `is_selected` flag. An id that does not belong to the product fails with NOT_FOUND and lists the ones that do; it never quietly returns a different shade.
include_reviews = true	optional	—	Return the product's top customer reviews inline, with full text, title, star rating, date, helpfulness votes, reviewer skin-tone/skin-type/eye/age context and photo URLs — plus the rating distribution and the product's UPC/EAN codes. Costs one extra upstream call (~27 KB at the default limit). Set false to skip it.
reviews_limit = 8	optional	0–100	How many reviews to embed (0-100). 100 is the upstream ceiling — bisected, 101 is refused. 0 keeps the summary (total, average, rating distribution, UPC/EAN) and returns no review bodies. Reviews are ~2.5 KB each, so this is the main lever on response size.
reviews_sort = most_helpful	optional	most_helpful · newest · oldest · highest_rating · lowest_rating	Which reviews count as 'top'. These are exactly the five options Sephora's own review widget offers, with the same underlying sort keys — read out of the product payload's own `reviewFilters`, not invented.
reviews_offset = 0	optional	0–10000	Skip this many reviews before returning `reviews_limit` of them — page through a product's full review history (`review_summary.total_reviews` tells you how many there are; some products have more than 17 000).
include_variant_images = false	optional	—	By default every variant carries its swatch and its own main image, and the FULL gallery is returned once at product level. Set true to also get each variant's complete alternate-image set — no extra request, just a much larger response (a 60-shade foundation carries about nine images per shade).

Try in playground →

Example request · search

curl -X POST https://api.reefapi.com/sephora/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"mascara","max_results":30}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}