> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Facets API: Get Collection Facets

> Facets API endpoint that returns facet values and result counts for a collection without running a full browse query, ideal for filter sidebars.

## Authorization

<ParamField header="X-Storefront-Access-Token" type="string" required>
  Token-based authentication header in the form of `<YOUR_LAYERS_TOKEN>`.
</ParamField>

## Headers

<ParamField header="Content-Type" type="string" default="application/json" required />

<ParamField header="Accept" type="string" default="application/json" required />

## Path parameters

<ParamField path="collection_handle" type="string" required>
  The handle of the collection to retrieve facets for.
</ParamField>

## Body

<ParamField body="facets" type="string[]" description="List of facets to include in the response.">
  Facets to be included. Accepts both exact facet codes (e.g., `"vendor"`, `"options.Size"`) and wildcard patterns (e.g., `"options.*"`, `"metafields.product.*"`).

  Wildcard patterns expand to all matching attribute codes. For example, `"options.*"` expands to all option facets like `"options.Size"` and `"options.Color"`. Wildcards must match at least one attribute code to be valid.

  **Examples:**

  ```json theme={null}
  // Exact facet codes
  "facets": ["vendor", "options.Size", "options.Color"]

  // Wildcard pattern
  "facets": ["options.*"]

  // Mixed exact and wildcard
  "facets": ["vendor", "options.*", "metafields.product.*"]
  ```
</ParamField>

<ParamField body="retrieveFacetCount" type="boolean" description="Retrieve facet count.">
  If the count of each facet value should be calculated
</ParamField>

<ParamField body="includeFacetRanges" type="boolean" descriptive="Return min/max range for facets with a numeric value.">
  If you want a min/max range for numeric facets such as price.
</ParamField>

<ParamField body="filter_group" type="object" description="A group of filter conditions using various operators.">
  Refer to our dedicated [Filter Expressions](/engine/filtering) guide to learn more about filter expressions.
</ParamField>

## Response

This endpoint returns facet metadata only — it does **not** return product results, pagination fields, or an `attributionToken`. If you need products alongside facets, use the [Browse API](/api-reference/browse) with `retrieveFacetCount` enabled instead.

<ResponseField name="facets" type="object">
  Object whose keys are facet attribute codes and whose values are objects mapping each facet value to its result count. Only returned when `retrieveFacetCount` is `true`.

  Counts are scoped to the visibility of the active shopping channel, so they always match the number of products a shopper can actually see in the collection for that channel. Products that are not published to the requester's channel, are B2B-only, or are hidden by a combined-listing role are excluded from every bucket. When the request is a mobile app request but the store does not have an [app sales channel](/help/configuration/configure-search-behavior#app-sales-channel) configured, counts fall back to the web channel.
</ResponseField>

<ResponseField name="facetRanges" type="object">
  Object whose keys are facet attribute codes and whose values are objects with `min` and `max` numeric properties. Only returned when `includeFacetRanges` is `true`.

  Ranges are computed only over products visible on the active shopping channel. A numeric range — for example, a price slider's `min` and `max` — cannot come from a product the shopper cannot see.
</ResponseField>

<ResponseField name="filters" type="object">
  Echo of the filter group expressions that were applied when computing the counts. Useful for verifying that the request's `filter_group` was interpreted as expected.
</ResponseField>

## When to use

Use this endpoint when you need facet data without fetching product results. Common scenarios include:

* **Pre-loading filter options**: Fetch available filter values before the user starts browsing
* **Sidebar filters**: Build filter UIs that show available options and counts independently of the product grid
* **Reducing payload size**: Avoid fetching full product data when you only need facet information

For combined product results and facets in a single request, use the [Browse API](/api-reference/browse) with `retrieveFacetCount` enabled instead.

<ResponseExample>
  ```json Request theme={null}
  POST /storefront/v1/summer-collection/facets

  {
    "facets": ["vendor", "product_type", "price_range"],
    "retrieveFacetCount": true,
    "includeFacetRanges": true
  }
  ```

  ```json Response theme={null}
  {
    "facets": {
      "vendor": {
        "Nike": 45,
        "Adidas": 30,
        "New Balance": 25,
        "Puma": 20,
        "Reebok": 15,
        "Vans": 15
      },
      "product_type": {
        "Shoes": 80,
        "Apparel": 50,
        "Accessories": 20
      }
    },
    "facetRanges": {
      "price_range": {
        "min": 29.99,
        "max": 249.99
      }
    },
    "filters": {}
  }
  ```
</ResponseExample>