Browse Facets

The browse facets endpoint lists all the customer-defined facets present in the current index, while the facet options endpoint (shown below) indicates all the facet options (values) available for a given facet group (key), along with counts for the number of items available for each.

This can be useful to validate the integrity of a catalog by checking the number of products present for each brand, or within each group (category) as well as to power facet listings for web interfaces.

The browse facets endpoint can be used with production-level loads. Given customers may potentially define thousands of facets, the full list of facets is sorted ascending alphabetically, and paginated.

The browse facets endpoint does not return individual item results - for this purpose reference the standard browse endpoint.

Request facets
curl -X GET -H "Content-Type: application/json" \
"[your API key]"
Request facets, but also show hidden facets
curl -X GET -H "Content-Type: application/json" \
"[your API key]&fmt_options[show_hidden_facets]=true"

HTTP Request#

GET[your API key]&page=1&num_results_per_page=20&fmt_options[show_hidden_facets]=true&fmt_options[show_protected_facets]=true

URL Parameters#

The URL parameters the endpoint accepts are shown below.

pageNo1The page number of the results
num_results_per_pageNo20The number of results per page to return
fmt_options[show_hidden_facets]NoFalseInclude facets configured as hidden
fmt_options[show_protected_facets]NoFalseInclude facets configured as protected

Response format overview#

"request": {
"response": {
"facets": [
"data": {},
"display_name": "Brand",
"name": "brand",
"type": "multiple"
"data": {},
"display_name": "Price",
"name": "price",
"status": {},
"type": "range"
"total_num_results": 2