---
title: "Facet counts for the current selection"
method: GET
path: "/api/knowledge/facets"
tags: ["Knowledge"]
---

# Facet counts for the current selection

`GET /api/knowledge/facets`

## Request

- Base URL: `https://api.historis.app`
- URL: `https://api.historis.app/api/knowledge/facets`
- Auth: HTTP bearer

Counts of contacts, tags and calendar months, each answering "how many notes if I click this". Tags and contacts are multi-select AND, so their buckets run over the SAME selection the list returns, the facet's own selected values included; the period bar is single-select, so its buckets run over that selection with its period bound cleared -- otherwise a bucket would predict a query the click does not run. clearedTotals is the same question for each bar's All chip: the total with that one axis cleared. Selected tags and personIds are always present, even at count 0. Months are UTC YYYY-MM buckets, cut on note creation or on a linked event's date per periodBasis.

## Query parameters

- `query` string
- `status` 'active' | 'archived' | 'all'
- `tags` string
- `personIds` string
- `since` string, date-time
- `until` string, date-time
- `updatedSince` string, date-time
- `updatedUntil` string, date-time
- `eventSince` string, date-time
- `eventUntil` string, date-time
- `periodBasis` 'created' | 'event'

## Response `200`

Facet counts

- object

## Other responses

- `400`: Request failed schema validation
- `401`: Missing or invalid credentials
- `429`: Rate limit exceeded for the caller's identity/plan
- `500`: Internal server error

---

[API](https://skmtc.dev/historis/apis/historis-api.md) · [All operations](https://skmtc.dev/historis/apis/historis-api/llms.txt) · [OpenAPI document](https://skmtc.dev/historis/apis/historis-api/revisions/fa382546b63e?raw)