---
title: "Get list of the possible facets for a given query"
method: GET
path: "/facets/{facets}"
tags: ["Product list page"]
---

# Get list of the possible facets for a given query

`GET /facets/{facets}`

Lists the possible facets for a given query.

>ℹ️ Migrate to [Intelligent Search API v1](https://developers.vtex.com/docs/api-reference/intelligent-search-api-v1) for HTTP caching (`Cache-Control: public, max-age=600`), lower latency, and explicit regionalization without relying on the segment cookie. The new endpoint is: `GET` [List filters for a search](https://developers.vtex.com/docs/api-reference/intelligent-search-api-v1#get-/facets/-facets-). See the [migration guide](https://developers.vtex.com/docs/guides/migrating-to-intelligent-search-api-v1).

>⚠️ When possible, use the store's production domain in the URL (for example, `https://apiexamples.com/api/io/_v/api/intelligent-search`) for a better performance. This is particularly important for headless integrations. In case it's not possible to use the store's production URL, prefer using `https://{accountName}.vtexcommercestable.com.br/api/io/_v/api/intelligent-search`.

If using this option in a fully headless store with no store domain configured, follow these steps:
1. Configure a domain by following the [Configuring the store domain](https://help.vtex.com/docs/tutorials/configuring-the-store-domain) guide.
2. Send the `Host` header with the configured domain:
```sh
curl --location 'https://{accountName}.vtexcommercestable.com.br/api/io/_v/api/intelligent-search/facets/' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Host: {configured domain}'
```

## Permissions

This endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).

## Path parameters

- `facets` string, nullable, required

## Query parameters

- `query` string
- `locale` string, nullable
- `hideUnavailableItems` boolean
- `removeHiddenFacets` boolean

## Response `200`

OK 

 List of facets for the given query.

- Facets — Response body object.
  - `facets` object[] — List of facets.
    - `values` object[] — Possible values.
      - `id` string — Value ID.
      - `quantity` number — Number of resulting products.
      - `name` string — Human-readable format of the facet value.
      - `key` string — Facet key.
      - `value` string — Facet value.
      - `selected` boolean — Defines whether the value is selected (`true`) or not (`false`).
      - `href` string — Query URL.
    - `type` 'TEXT' | 'PRICERANGE' | 'DELIVERY' — Facet type, which can be: - `TEXT`: The value is a simple text. - `PRICERANGE`: The value contains the property `range` representing the minimum and the maximum price for the query. - `DELIVERY`: The value represents a delivery option. Only appears in searches using [Delivery Promise](https://help.vtex.com/docs/tutorials/delivery-promise-beta).
    - `name` string — Human-readable format of the facet key.
    - `hidden` boolean — Defines whether the client-side should hide the facet (`true`) or not (`false`).
    - `key` string — Facet key.
    - `quantity` number — Number of possible values.
  - `sampling` boolean — Indicates whether there was sampling in the aggregation of facets or not. In search results that have many products, only the first 30000 will be aggregated to avoid performance issues.
  - `breadcrumb` object[] — Generated breadcrumb for the given query.
    - `name` string — Human-readable format of the facet key.
    - `href` string — Query link.
  - `queryArgs` object — Term and facets used in the query.
    - `query` string — Search term used in the query.
    - `selectedFacets` object[] — Facets used in the query.
      - `key` string — facet key.
      - `value` string — facet value.
  - `translated` boolean — Defines whether the facets were translated by Intelligent Search (`true`) or not (`false`).

## Changes

- **2026-06-25** `838b6b0fe9ac` — 1 warning, 1 info
  - added the new `DELIVERY` enum value to the `facets/items/type` response property for the response status `200`
  - added the new optional `query` request parameter `removeHiddenFacets`
- **2026-02-12** `961dac7d3929` — 2 info
  - api tag `Product list page` added
  - api tag `Product List Page` removed

[Change history](https://skmtc.dev/vtex/apis/intelligent-search-api-legacy/changes/facets/:facets/get.md)

---

[API](https://skmtc.dev/vtex/apis/intelligent-search-api-legacy.md) · [All operations](https://skmtc.dev/vtex/apis/intelligent-search-api-legacy/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vtex/intelligent-search-api-legacy/revisions/62d8bce60c7e/schema)