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

# 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

<ParamField header="Authorization" type="string" required>
  Bearer token (e.g. <code>Authorization: Bearer YOUR\_API\_KEY</code>)
</ParamField>

## Query parameters

<ParamField query="q" type="string">
  Optional search query applied before faceting.
</ParamField>

<ParamField query="locale" type="string" default="en">
  Locale for search. Options: `en`, `ro`
</ParamField>

<ParamField query="type" type="string">
  Filter by product type before computing facets.
</ParamField>

<ParamField query="status" type="string">
  Filter by status before computing facets.
</ParamField>

<ParamField query="organizationId" type="string">
  B2B: Filter by organization visibility before computing facets (UUID format).
</ParamField>

## Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.voyantcloud.com/v1/products/search/facets?locale=en" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.voyantcloud.com/v1/products/search/facets?locale=en",
    {
      headers: {
        Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
      },
    }
  )

  const facets = await response.json()
  console.log(facets.facets)
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
    'https://api.voyantcloud.com/v1/products/search/facets',
    params={'locale': 'en'},
    headers={'Authorization': f"Bearer {os.environ['VOYANT_API_KEY']}"}
  )

  facets = response.json()
  print(facets['facets'])
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.voyantcloud.com/v1/products/search/facets?locale=en');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . getenv('VOYANT_API_KEY')
  ]);

  $response = curl_exec($ch);
  $facets = json_decode($response, true);
  print_r($facets['facets']);
  ?>
  ```
</CodeGroup>

## Response

<ResponseField name="facets" type="object" required>
  Facet attributes and their values with counts (all facet attributes returned).
</ResponseField>

<ResponseField name="exhaustiveFacetsCount" type="boolean" required>
  Whether the facet count is exact (`true`) or approximate (`false`)
</ResponseField>

<ResponseField name="processingTimeMS" type="integer" required>
  Processing time (milliseconds)
</ResponseField>

<ResponseField name="tookMs" type="integer" required>
  Total request time (milliseconds)
</ResponseField>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "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
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized"
  }
  ```

  ```json 503 Service Unavailable theme={null}
  {
    "error": "Search service unavailable"
  }
  ```
</ResponseExample>

## 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`:

```javascript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Search products" icon="search" href="/api-reference/products/search">
    Search across your product catalog
  </Card>

  <Card title="List products" icon="list" href="/api-reference/products/list-products">
    Browse products with database filtering
  </Card>
</CardGroup>