---
title: "Get Feed Facets"
method: GET
path: "/v1/feed/facets"
---

# Get Feed Facets

`GET /v1/feed/facets`

## Request

- Base URL: `https://api.shortkit.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://api.shortkit.dev/v1/feed/facets`
- Auth: none declared

Catalogue breakdown of this org's feed by one filter dimension.

``by`` (required) is ``tags``, ``section``, ``author``, ``content_type``
or ``metadata.<key>`` — the include dimensions ``/feed/filter`` accepts.
``min`` drops values with fewer matches. Honors the same media negotiation
(``supportedContentTypes``/``mediaContractVersion``) and ``exclude.*``
rules as ``/feed/filter``, so for any value ``v``::

    data.counts[v] == total items /feed/filter?<by>=v would page through

Counts are over published, ready, non-deleted content of a supported type
(``base_feed_conditions``); each content row counts once per distinct
value it carries. Response::

    {"data": {"by": "tags", "counts": {"baseball": 183, "hockey": 111}},
     "meta": {"request_id": "..."}}

``counts`` is ordered by count descending, then value ascending. Invalid
``by`` → 400. One aggregate query per org/dimension/filter combination,
shared through Redis for ``FACETS_CACHE_TTL_S`` (60 s) when Redis is
configured — the publishable key ships in client apps that call this on
every launch, and the unnest over the org's catalogue is the kind of
hot-table scan ``robots_results.org_tag_taxonomy`` bounds elsewhere.

Orgs with ``discovery_feed_enabled`` route filtered requests through the
discovery pipeline, which (absent media negotiation) only serves
``video``/``live_stream``; the counts mirror that pool, and equal its
``X-Pool-Size`` header for the same filter. Per-viewer "seen" dedupe
happens after the pool, so a given viewer may receive fewer items.

## Query parameters

- `by` string, nullable
- `min` integer

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-04** `82ba66751b25`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shortkit/apis/shortkit-api/changes/v1/feed/facets/get.md)

---

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