ulta-research

Ulta Beauty research

Browse and search Ulta Beauty's catalog and pull product detail, shade variants, questions, reviews, and nearby store locations — all as normalized JSON from the Crawlora API, with no HTML scraping.

When to use this skill

• "Find [product] on Ulta" or "what does Ulta sell for [need]?"
• "Browse Ulta's [department] category" / "filter by [brand/benefit]."
• "What do customers ask and say about this Ulta product before I

recommend it?" (Q&A + reviews)

• "Find shade/sku options for this Ulta product."
• "Is there an Ulta store near [zip/city]?"

Setup (one-time)

• Get a free Crawlora API key (2,000 credits/mo, no card) at https://crawlora.net.
• Set CRAWLORA_API_KEY in the environment before running the helper.
• The helper reads CRAWLORA_API_KEY from the environment and sends requests to https://api.crawlora.net/api/v1. Missing/invalid key → 401.

How it works

1. Discover categories — /ulta/categories lists the storefront

navigation (department, group, and a category value ready to pass to /ulta/category).

1. Browse or search — /ulta/category (category) paginates a

category's product grid and returns guided-navigation filter facet codes to narrow it; /ulta/search (query) does keyword search instead. /ulta/suggest (query) returns typeahead suggestions plus each suggestion's top product matches, useful for finding query ideas or a featured best match for a partial term.

1. Detail — /ulta/product/{productId} fetches full product detail:

name, brand, description, pricing, rating, and every purchasable color/shade variant; pass sku to pin a specific shade.

1. Q&A and reviews — /ulta/product/questions and

/ulta/product/reviews (both keyed by product_id) pull paginated customer questions/answers and written reviews plus the rating summary.

1. Nearby stores — /ulta/stores resolves a search string (zip,

city, address) or explicit lat/lng to nearby physical Ulta locations, with hours, services, and phone.

Full endpoint list, methods, and params: `reference/endpoints.md`.

Calling the API

# Search Ulta by keyword:
scripts/crawlora.sh /ulta/search query="vitamin c serum" | jq '.'

# Browse a category, filtered:
scripts/crawlora.sh /ulta/category category="shop/skin-care/serums" filter="BENEFIT--BRIGHTENING" | jq '.'

# Product detail (path param) for a specific shade:
scripts/crawlora.sh /ulta/product/pimprod2020260 sku=2540468 | jq '.data'

# Nearby stores:
scripts/crawlora.sh /ulta/stores search="60614" | jq '.'

Use scripts/crawlora.sh for all requests; it keeps the API key out of command-line arguments.

Endpoint reference

See `reference/endpoints.md` for every Ulta Beauty endpoint this skill uses (method, path, params, description).

Examples

• Filtered category browse: /ulta/categories to find a

department's category value, then /ulta/category paginated with filter set to a facet code from that category's own response, to narrow by benefit/brand.

• Product due diligence: /ulta/product/{productId} for

price/rating/shades, then /ulta/product/questions and /ulta/product/reviews (both by product_id) to summarize what shoppers ask and say before recommending it.

• Find a store: /ulta/stores with search set to a zip code or

city, then check hours/services on the closest result.

Notes & limits

• Credits / pay-on-success: billed only on 2xx; free tier 2,000 credits/mo.

Key at https://crawlora.net.

• Public data only — public Ulta Beauty product/category/store pages; respect Ulta's terms.
• Security: key lives in CRAWLORA_API_KEY only — never hardcode, query-param, or commit it.
• Results are paginated — pass page (1-based) to walk category, search,

questions, and reviews listings.

• Product identity is `product_id` (aka productId, from a search

result's product_id field or the product URL) — /ulta/product/{productId}, /ulta/product/questions, and /ulta/product/reviews all key off it; sku is optional and only narrows /ulta/product/{productId} to one shade/color variant.

• /ulta/stores needs either search or both lat and lng; an

unresolved search or an empty radius returns a well-formed empty result, not an error — same for a nonsense search/query on /ulta/search and /ulta/suggest.

• An unrecognized category on /ulta/category returns 404, but an

unrecognized product_id on /ulta/product/questions or /ulta/product/reviews returns a normal empty result instead.