API Reference

API Reference

The Products API gives you live, filterable access to the BeautyFeeds catalog, plus self-service credit-metered access for expanding what your account can pull.

Authentication

Every request needs your account's API key in a header:

X-API-KEY: your_api_key_here

Find your key from your dashboard's API Settings. Requests without a valid key, or from an inactive subscription, return 401 Unauthorized.

Endpoints

Filtering

All four endpoints accept the same filters, and each one takes a comma-separated list for an OR match — e.g. brand_name=Fenty,Sephora matches either brand in one call:

• brand_name — filter by brand
• category — filter by category
• site_name — filter by retailer, e.g. sephora.com
• country — filter by country code, e.g. us
• uniq_ids — a comma-separated list of exact product IDs, for selecting specific products instead of an entire brand or category
• updated_within — last_7_days, last_30_days, or last_1_year; only products re-crawled within that window. Available on Pro and Enterprise plans.

Example response

A real response, from an org with a large assigned catalog and no active filter (matched_in_catalog/expansion_notice only populate when a filter is given):

{
  "meta": {
    "total_results": 27294,
    "total_pages": 546,
    "current_page": 166,
    "per_page": 50,
    "status": "success",
    "assigned_urls_count": 27294,
    "matched_in_catalog": null,
    "next_page_url": "https://api.beautyfeeds.io/api/v1/beauty_products?page=167&per_page=50",
    "previous_page_url": "https://api.beautyfeeds.io/api/v1/beauty_products?page=165&per_page=50",
    "expansion_notice": null,
    "ingredients_data_notice": "Ingredient/INCI fields are extracted and normalized automatically from retailer pages — not manually verified, may not be 100% accurate."
  },
  "data": [
    { "uniq_id": "4d8d2fa92f8559b1", "site_name": "amazon.com", "country": "us", "product_name": "...", "brand_name": "..." }
  ]
}

Ingredient and INCI-formatted fields (ingredients, ingredients_formatted, inci_format, raw_ingredients) come from automated parsing of retailer pages, not manual verification, and may not be 100% accurate. They're a strong starting point for formulation research, not a certified source — always confirm against the original product page before relying on them for compliance or labeling decisions.

matched_in_catalog is the full-catalog count for your filter, not just what you're currently entitled to — if it's higher than total_results, there's more available via assign. expansion_notice spells the same gap out in words; both are null when there's nothing more to unlock.

List-shaped fields (ingredients, variants, breadcrumbs, and similar) come back as real JSON arrays/objects, not JSON-encoded strings — no re-parsing needed on your end.

The exact set of fields in data depends on your plan — see Pricing or the full Plans & Features reference for what each tier includes.

How credits work for API access

A credit is spent once per product, the moment it's newly granted through assign — querying it afterward, any number of times, is free for the rest of your current billing cycle. Continued access to your assigned products renews with your billing cycle rather than being a one-time unlock, since the underlying catalog itself is kept fresh by ongoing re-crawls. See Downloads & Exports for how the same credit balance works for dataset exports.

Reviews (analytics & pricing only)

Reviews aren't part of the Products API — GET /api/v1/reviews/stats is a separate endpoint, served from app.beautyfeeds.io rather than api.beautyfeeds.io, since reviews live in a different datastore from products. Same X-API-KEY auth and filters, scoped to products you already have Products API access to. It returns a review count and price estimate — the review records themselves are still purchased and downloaded from Global Data, not delivered by this endpoint.

Rate limits & errors