---
title: "Retrieve facet options (values) by facet name"
method: GET
path: "/browse/facet_options"
tags: ["Browse facets"]
---

# Retrieve facet options (values) by facet name

`GET /browse/facet_options`

Retrieve facet options for end users.

## Query parameters

- `key` string, required — The key of the index to use.
- `section` string — The section of the index to use. Defaults to `Products`.
- `num_results_per_page` integer — The number of results per page to return.
- `page` integer — The page of results to return.
- `offset` integer — The number of results to skip from the beginning. Cannot be used together with `page`.
- `now` string, date-time — A date time representing the current moment in time when applying filtering by product age. Used to emulate "past/future" requests. Requires authentication.
- `fmt_options` FacetFmtOptions
  - `show_hidden_facets` boolean — A flag to return all facets configured as `hidden` in `response.facets`.
  - `hidden_facets` string[] — A list of specific hidden facets to return in the response. Unlike `show_hidden_facets` this parameter allows the request to control which hidden facets are returned. Used to return facets for a particular store or user segment.
  - `show_hidden_facet_options` boolean — A flag to return all `hidden` facets options in the response.
  - `show_protected_facets` boolean — A flag to return all `protected` facets in the response. Requires authentication.
  - `show_internal_facets` boolean
- `origin_referrer` string — The url or app location where the request originated.
- `c` string — The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
- `facet_name` string, required — The name of the facet
- `us` string[] — A customer defined context (such as `vip-club-member`) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple `us` arguments.
- `ui` string — A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.
- `s` integer — An integer representing the users session number (starting with `1`), incremented after a 30 minute period of inactivity.
- `i` string — A globally unique identifier for the user browser (or mobile application instance) making the request.

## Response `200`

OK

- BrowseFacetOptionsGetResponse
  - `request` object, required — The request arguments how they were interpreted by the API. This field is of arbitrary type, ie it doesn't have a guaranteed schema, and data from it shouldn't be used programmatically, it is for debugging purposes only.
  - `result_id` string
  - `response` BrowseFacetOptionsResponse, required
    - `facets` union[], required — An array with the single requested facet.
      - union
        - union
          - BoundariesRangeFacet
            - `options` FacetOption[] — A list of facet option configurations to create and associate with this facet configuration. Default value is `[]` (empty list).
              - …
            - `name` string, required — The facet name used to refer to the facet in your catalog. Must be unique inside the section and key.
            - `type` 'range', required
            - `display_name` string — The name of the facet to present to end users. Default value is `null`, in which case the `name` will be presented.
            - `sort_order` 'relevance' | 'value' | 'num_matches'
            - `sort_descending` boolean — `true` if this facet group's options should be sorted in descending order, `false` to sort ascending. Default value is `true` if `sort_order` is `relevance` or `num_matches` and `false` for `value`. Setting `sort_order: relevance` will set `sort_descending: true` for `POST`, `PUT`, `PATCH` endpoints if `sort_descending` is not explicitly set in the request.
            - `range_type` 'static'
            - `range_format` 'boundaries', required
            - `range_inclusive` 'above' | 'below'
            - `range_limits` union[] — Defines the cut-off points for generating static range buckets. Expects list of sorted numbers (like `[10, 25, 40]`). Default value is `null`
              - …
            - `match_type` 'any' | 'all' | 'none'
            - `position` integer — Used to slot facet groups to fixed positions. Default value is `null`.
            - `hidden` boolean — Specifies whether the facet is hidden from users. Use this for facet data that you don't want shown to end users, but that isn't sensitive.
            - `protected` boolean — Specifies whether the facet is protected from users. Setting this to `true` will require authentication to view the facet.
            - `countable` boolean — Specifies whether counts for each facet option should be calculated and shown in the response. Setting this to `false` will skip counting these options, improving performance for facets with high cardinality.
            - `options_limit` integer — Maximum number of options of facet type `multiple` to return in search responses. If absent, the default limit is applied.
            - `data` object — Dictionary with any extra facet data. Default value is `{}` (empty dictionary).
          - OptionsRangeFacet
            - `options` FacetOption[] — A list of facet option configurations to create and associate with this facet configuration. Default value is `[]` (empty list).
              - …
            - `name` string, required — The facet name used to refer to the facet in your catalog. Must be unique inside the section and key.
            - `type` 'range', required
            - `display_name` string — The name of the facet to present to end users. Default value is `null`, in which case the `name` will be presented.
            - `sort_order` 'relevance' | 'value' | 'num_matches'
            - `sort_descending` boolean — `true` if this facet group's options should be sorted in descending order, `false` to sort ascending. Default value is `true` if `sort_order` is `relevance` or `num_matches` and `false` for `value`. Setting `sort_order: relevance` will set `sort_descending: true` for `POST`, `PUT`, `PATCH` endpoints if `sort_descending` is not explicitly set in the request.
            - `range_type` 'static'
            - `range_format` 'options', required
            - `range_inclusive` 'above' | 'below'
            - `range_limits` union[], required — Defines the cut-off points for generating static range buckets. Expects list of sorted numbers (like `[10, 25, 40]`). Default value is `null`
              - …
            - `match_type` 'any' | 'all' | 'none'
            - `position` integer — Used to slot facet groups to fixed positions. Default value is `null`.
            - `hidden` boolean — Specifies whether the facet is hidden from users. Use this for facet data that you don't want shown to end users, but that isn't sensitive.
            - `protected` boolean — Specifies whether the facet is protected from users. Setting this to `true` will require authentication to view the facet.
            - `countable` boolean — Specifies whether counts for each facet option should be calculated and shown in the response. Setting this to `false` will skip counting these options, improving performance for facets with high cardinality.
            - `options_limit` integer — Maximum number of options of facet type `multiple` to return in search responses. If absent, the default limit is applied.
            - `data` object — Dictionary with any extra facet data. Default value is `{}` (empty dictionary).
        - SingleOrMultipleFacet
          - `type` 'single' | 'multiple', required — If a facet is of type `single`, then only one of the options may be selected (e.g: display as radio button). If the type is `multiple`, then multiple options may be selected (e.g: display as checkboxes).
          - `name` string, required — The name of the facet. This should be passed in the filters parameter when a facet of this type is selected. `filters[name]=value`
          - `display_name` string, required — The name of the facet as it is displayed to end users. Note that in `filters` parameter you need to use not `display_name` but `name`.
          - `hidden` boolean, required — The boolean value saying whether facet is available for interaction.
          - `data` object, required — Object containing custom data associated with this facet. An empty object (`{}`) if no data is currently associated with this facet.
          - `options` FacetOption[] — An array of possible facet values matching this search. By default, facet options are sorted by relevance. Number of options is limited, by default, to 500. But the limit can be configured per [facet](/reference/v1-facets-create-facet) key.
            - `value` string, required — A value for this facet option. Must be unique for particular facet.
            - `value_alias` string — A value alias. It is used to merge several different but semantically similar facet options into one. For example, 'dark blue' and 'light blue' can be aliased to 'blue'.
            - `replace_value_alias` boolean — Determines the handling of a value alias when present. If set to `true`, exclusively considers the aliased value. If `false`, both the original and the aliased values are used.
            - `display_name` string — A display name for this facet option.
            - `position` integer — Used to order facet options.
            - `data` object — Dictionary with any extra facet option data. Default value is `null`.
            - `hidden` boolean — Specifies whether the facet option is hidden from users.
        - HierarchicalFacet
          - `options` FacetOption[] — A list of facet option configurations to create and associate with this facet configuration. Default value is `[]` (empty list).
            - `value` string, required — A value for this facet option. Must be unique for particular facet.
            - `value_alias` string — A value alias. It is used to merge several different but semantically similar facet options into one. For example, 'dark blue' and 'light blue' can be aliased to 'blue'.
            - `replace_value_alias` boolean — Determines the handling of a value alias when present. If set to `true`, exclusively considers the aliased value. If `false`, both the original and the aliased values are used.
            - `display_name` string — A display name for this facet option.
            - `position` integer — Used to order facet options.
            - `data` object — Dictionary with any extra facet option data. Default value is `null`.
            - `hidden` boolean — Specifies whether the facet option is hidden from users.
          - `name` string, required — The facet name used to refer to the facet in your catalog. Must be unique inside the section and key.
          - `type` 'hierarchical', required
          - `display_name` string — The name of the facet to present to end users. Default value is `null`, in which case the `name` will be presented.
          - `sort_order` 'relevance' | 'value' | 'num_matches'
          - `sort_descending` boolean — `true` if this facet group's options should be sorted in descending order, `false` to sort ascending. Default value is `true` if `sort_order` is `relevance` or `num_matches` and `false` for `value`. Setting `sort_order: relevance` will set `sort_descending: true` for `POST`, `PUT`, `PATCH` endpoints if `sort_descending` is not explicitly set in the request.
          - `range_type` 'static'
          - `range_format` 'boundaries' | 'options'
          - `range_inclusive` 'above' | 'below'
          - `range_limits` union[] — Defines the cut-off points for generating static range buckets. Expects list of sorted numbers (like `[10, 25, 40]`). Default value is `null`
            - union
              - …
          - `match_type` 'any' | 'all' | 'none'
          - `position` integer — Used to slot facet groups to fixed positions. Default value is `null`.
          - `hidden` boolean — Specifies whether the facet is hidden from users. Use this for facet data that you don't want shown to end users, but that isn't sensitive.
          - `protected` boolean — Specifies whether the facet is protected from users. Setting this to `true` will require authentication to view the facet.
          - `countable` boolean — Specifies whether counts for each facet option should be calculated and shown in the response. Setting this to `false` will skip counting these options, improving performance for facets with high cardinality.
          - `options_limit` integer — Maximum number of options of facet type `multiple` to return in search responses. If absent, the default limit is applied.
          - `data` object — Dictionary with any extra facet data. Default value is `{}` (empty dictionary).
    - `total_num_results` integer, required — Total count of facet options for the requested facet.

## Other responses

- `400` — Validation Error

---

[API](https://skmtc.dev/constructor/apis/autocomplete.md) · [All operations](https://skmtc.dev/constructor/apis/autocomplete/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/constructor/autocomplete/revisions/2d33330633b6/schema)