Sephora API endpoint
Searches Sephora's product catalog by keyword, with real page-based pagination. Returns products with brand, pricing, rating, and review count. Sephora's own search never returns a genuine zero-result state for a nonempty keyword -- an unrecognized/nonsense keyword still returns a full, unrelated fallback result set rather than an empty one. price_min/price_max must be provided together (whole dollars) -- upstream silently ignores a one-sided price range rather than filtering or erroring, so this endpoint rejects a one-sided range as invalid instead of passing it through. brand and filter each accept multiple values (OR'd together within the same facet); brand/rating_min/is_new/filter/price_min/price_max can all be combined with each other (AND'd together across different facets).
/sephora/searchQuery parameters:
query: required. Free-text search keywords, e.g. mascara.page: optional, 1-based, defaults to 1.page_size: optional, 1 to 100, defaults to 60.sort_by: optional, defaults to featured. One of: featured,
top_rated, new, best_selling, price_low_to_high,
price_high_to_low.price_min: optional, whole dollars, no cents. Must be provided together
with price_max -- Sephora's own upstream silently ignores a one-sided
price range instead of filtering or erroring on it, so this endpoint
rejects a one-sided range as an invalid param rather than passing it
through.price_max: optional, whole dollars, no cents. Must be provided together
with price_min, for the same reason.brand: optional, repeatable. One or more exact brand names (as returned
in a product's brand_name, e.g. Lancôme, tarte) to filter to;
repeat the param for multiple values, which are OR'd together (e.g.
Lancôme + ILIA returns products from either brand). See
sephora-brands to discover every accepted value
rather than guessing one.rating_min: optional, 1 to 4. Filters to products rated at least
this many stars.is_new: optional, defaults to false. When true, filters to products
flagged New.filter: optional, repeatable, facet:value form (e.g. formulation:serum). facet must be one of: benefits, ingredientpreferences, colorfamily, formulation, size, shoppingpreferences, agerange, skintype, finish, skinconcerns, coverage, hairtype, hairconcerns, hairtexture. value is free text -- the catalog's own current value list per facet (e.g. colorfamily accepts black, nude, red, ...) isn't a small fixed enum and varies by query, so it isn't exhaustively listed here; Sephora's own search-page filter UI is the source of truth for a given keyword's available values. Repeating filter with the same facet OR's those values together (e.g. filter=colorfamily:black&filter=colorfamily:red matches either); a different facet ANDs with everything else.brand, rating_min, is_new, filter, and price_min/price_max can
all be combined with each other; combined filters are AND'd together (e.g.
brand=Lancôme&rating_min=4 returns only Lancôme products rated 4 stars or
higher).
Notable response behavior:
total_products
and count reflect whatever the upstream actually returned.list_price/value_price are kept as Sephora's own display-formatted
strings (e.g. "$16.00 - $30.00") since a search card's price is often a
range across a product's own color/shade variants -- only
/sephora/product (scoped to one specific product) exposes fully resolved
per-variant pricing.related_searches lists Sephora's own suggested related keywords, when
present.| Field | Filled in, of 40 checked | Values in the sample |
|---|---|---|
| product_id | 40 | |
| sku_id | 40 | |
| brand_name | 40 | “Lancôme” and 22 other values |
| product_name | 40 | “Lash Idôle Lengthening & Volumizing Mascara” and 39 other values |
| list_price | 40 | “$16.00 - $30.00” and 27 other values |
| rating | 40 | 3.7 to 4.76, median 4.16 |
| review_count | 40 | 107 to 19,691, median 1,752 |
| more_colors | 39 | 1 to 5, median 2 |
| image_url | 40 | sephora.com |
| url | 40 | sephora.com |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| query | string | Yes | Search keyword | mascara | |
| page | integer | No | 1 | Result page, 1-based, defaults to 1 | 1 |
| page_size | integer | No | 60 | Results per page, 1 to 100, defaults to 60 | 60 |
| sort_by | string | No | featured | Sort order, defaults to featured Allowed values: featured, top_rated, new, best_selling, price_low_to_high, price_high_to_low. | featured |
| price_min | integer | No | Minimum price in whole dollars; must be set together with price_max | 15 | |
| price_max | integer | No | Maximum price in whole dollars; must be set together with price_min | 30 | |
| brand | array<string> | No | One or more exact brand names to filter to (OR'd together); repeat the param for multiple values | Lancôme | |
| rating_min | integer | No | Minimum star rating, 1 to 4 | 4 | |
| is_new | boolean | No | When true, filters to products flagged New | false | |
| filter | array<string> | No | Additional facet:value filters, repeat the param for multiple; facet must be one of: benefits, ingredientpreferences, colorfamily, formulation, size, shoppingpreferences, agerange, skintype, finish, skinconcerns, coverage, hairtype, hairconcerns, hairtexture | formulation:serum | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/sephora/search?query=mascara&page=1&sort_by=featured&is_new=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"query": "mascara",
"page": 1,
"page_size": 60,
"sort_by": "featured",
"total_products": 180,
"count": 2,
"related_searches": [
"foundation",
"highlighter"
],
"products": [
{
"product_id": "P520769",
"sku_id": "2948230",
"brand_name": "tarte",
"product_name": "Mini Shape Tape Concealer + Tubing Mascara Set",
"list_price": "$25.00",
"value_price": "$30.00",
"rating": 5,
"review_count": 2,
"more_colors": 8,
"image_url": "https://www.sephora.com/productimages/sku/s2948230-main-zoom.jpg",
"url": "https://www.sephora.com/product/travel-size-shape-tape-tubing-set-P520769?skuId=2948230"
},
{
"product_id": "P446676",
"sku_id": "1234567",
"brand_name": "Lancôme",
"product_name": "Lash Idôle Lengthening & Volumizing Mascara",
"list_price": "$29.00",
"rating": 4.5,
"review_count": 9021,
"sponsored": true,
"image_url": "https://www.sephora.com/productimages/sku/s1234567-main-zoom.jpg",
"url": "https://www.sephora.com/product/lash-idole-P446676"
}
],
"source_url": "https://www.sephora.com/api/v2/catalog/search/?...",
"fetched_at": "2026-08-15T12:00:00Z"
}
}Request schema
No body schema
Response schema
#/definitions/sephora.searchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | sephora.SearchResponse | No | ||||
| data.brand | array | No | ||||
| data.count | integer | No | ||||
| data.fetched_at | string | No | ||||
| data.filter | array | No | ||||
| data.is_new | boolean | No | ||||
| data.page | integer | No | 1 | |||
| data.page_size | integer | No | 60 | |||
| data.price_max | integer | No | 30 | |||
| data.price_min | integer | No | 15 | |||
| data.products | array | No | ||||
| data.products[].brand_name | string | No | tarte | |||
| data.products[].image_url | string | No | ||||
| data.products[].list_price | string | No | $25.00 | |||
| data.products[].more_colors | integer | No | ||||
| data.products[].product_id | string | No | P520769 | |||
| data.products[].product_name | string | No | ||||
| data.products[].rating | number | No | 4.5 | |||
| data.products[].review_count | integer | No | ||||
| data.products[].sku_id | string | No | ||||
| data.products[].sponsored | boolean | No | ||||
| data.products[].url | string | No | ||||
| data.products[].value_price | string | No | ||||
| data.query | string | No | mascara | |||
| data.rating_min | integer | No | 4 | |||
| data.related_searches | array | No | ||||
| data.sort_by | string | No | featured | |||
| data.source_url | string | No | ||||
| data.total_products | integer | No | 180 | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/sephora/search?query=mascara&page=1&sort_by=featured&is_new=true" \
-H "x-api-key: $CRAWLORA_API_KEY"