Search facets

GET /v1/products/search/facets - Retrieve available facet values for products

Endpoint

GET https://api.voyantcloud.com/v1/products/search/facets

Retrieve all available facet attributes and their values for the current workspace query. Counts are computed after deduplication so filters stay accurate.

Authentication

Authorization · string · required

Bearer token (e.g. Authorization: Bearer YOUR_API_KEY)

Query parameters

q · string

Optional search query applied before faceting.

locale · string · default: "en"

Locale for search. Options: en, ro

type · string

Filter by product type before computing facets.

status · string

Filter by status before computing facets.

organizationId · string

B2B: Filter by organization visibility before computing facets (UUID format).

Request example

cURL

curl "https://api.voyantcloud.com/v1/products/search/facets?locale=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

facets · object · required

Facet attributes and their values with counts (all facet attributes returned).

exhaustiveFacetsCount · boolean · required

Whether the facet count is exact (true) or approximate (false)

processingTimeMS · integer · required

Processing time (milliseconds)

tookMs · integer · required

Total request time (milliseconds)

200 Success

{
  "facets": {
    "type": {
      "tour": 156,
      "cruise": 89,
      "experience": 43
    },
    "status": {
      "active": 210,
      "draft": 12
    },
    "categories": {
      "adventure": 89,
      "cultural": 67,
      "nature": 45
    },
    "tags": {
      "Black Friday": 23,
      "Featured": 45,
      "family-friendly": 78
    },
    "countries": {
      "ro": 120,
      "it": 45,
      "fr": 32
    },
    "regions": {
      "europe": 180,
      "asia": 28
    },
    "priceFromCurrency": {
      "EUR": 150,
      "USD": 62
    },
    "source": {
      "main": 180,
      "marketplace": 32
    }
  },
  "exhaustiveFacetsCount": true,
  "processingTimeMS": 12,
  "tookMs": 45
}

Features

Available facets

The following facet attributes are returned:

Facet	Description	Filter syntax
type	Product type	type:=tour
status	Product status	status:=active
categories	Category assignments	categories:=[adventure]
tags	Product tags	tags:=[Black Friday]
countries	Countries visited (ISO codes)	countries:=[ro]
regions	Geographic regions	regions:=[europe]
priceFromCurrency	Price currency	priceFromCurrency:=EUR
source	Product source	source:=main

Using facets for filtering

Use the facet values with the filters parameter in /products/search:

// Get facets first
const facetsResponse = await fetch('/v1/products/search/facets?locale=en', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
const { facets } = await facetsResponse.json();

// Build filter from user selections
const filters = 'tags:=[Black Friday] && countries:=[ro]';

// Search with filter
const searchResponse = await fetch(
  `/v1/products/search?filters=${encodeURIComponent(filters)}`,
  { headers: { Authorization: `Bearer ${apiKey}` } }
);

Notes

• Facet counts are computed after workspace isolation and deduplication for accurate totals.
• Supports the same pre-filters as product search (q, type, status, organizationId, locale).

Related endpoints

Search products

Search across your product catalog

List products

Browse products with database filtering