---
title: "Count facets"
method: POST
path: "/v0/facets"
tags: ["Facets"]
---

# Count facets

`POST /v0/facets`

## Request

- Base URL: `https://docs.quivr.thevibecompany.co` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.quivr.thevibecompany.co/v0/facets`
- Auth: HTTP bearer

Exact document counts for projected metadata fields across authorized Corpora. Uses content:read and validates every requested Corpus before resolving mappings, including Corpora excluded for missing facet or predicate fields. Exclusions use the same excluded_corpora shape and rules as search and metadata-filtered listing. All fields are aggregated in one read snapshot from current baseline-ready, non-quarantined Versions; withdrawn Records and Tombstones are excluded immediately. Each distinct array value counts a document once. Missing field values contribute no bucket. Common metadata.* fields and custom fields declared with the filter role are supported. Incompatible types across Corpora return 422 invalid_query. Existing projections without metadata require rebuilding (422 metadata_filter_unavailable). Each field returns at most its limit, selected by descending count then JSON value text in byte order for ties. UTC date buckets are then returned chronologically; empty date buckets are omitted. Histograms require day, month or year on datetime fields; interval on another type is invalid_query. Counts are independent of search and listing reads and can change with ingestion. No text query or ranking is applied. Each API process admits at most 8 active facet requests; excess work returns retryable 503 content_unavailable with Retry-After: 1. Requests have a 25-second execution deadline. With accuracy fast, counts may instead come from each Corpus's stored snapshot, exact as of the response's as_of and refreshed in the background while it is read, when the request has no predicate or only whole UTC days of the single date field it counts; otherwise from an exact count that ends within about a second, or else estimates scaled from a uniform sample of the Corpora's Records, marked approximate with their sample_fraction. Exact responses carry neither as_of nor approximate.

## Request body

- FacetRequest
  - `corpus_ids` string[], required
  - `fields` FacetField[], required: Distinct logical metadata field names, in response order.
    - `field` string, required
    - `limit` integer
    - `interval` 'day' | 'month' | 'year': Required only for datetime fields; bucket start in UTC.
  - `filter` FacetFilter: Candidate filter applied before ranking. Every present condition must hold. A requested Corpus served by a Projection Generation built before source filtering existed returns 422 source_filter_unavailable; rebuild that Corpus once (rebuildCorpusProjection) to enable it. Unfiltered search is unaffected.
    - `source_namespaces` string[]: Keep only Records whose Source Namespace is one of these values. Ranking and the limit apply within the filtered set, so a source's best matches are returned even when other sources outrank them.
    - `metadata` MetadataFilter[]: ANDed typed filters. Common fields use metadata.language, metadata.published_at, metadata.source_type, metadata.source, metadata.author, metadata.subjects, metadata.tags, metadata.country and metadata.place. Other names require the filter role in the Corpus's effective retrieval mapping. Corpora missing a requested filter field are excluded and reported. A metadata-capable generation is required; rebuild older Corpora first (422 metadata_filter_unavailable).
      - union: Every present condition must hold. Field names are unique within a request; at most 16 predicates. Wrong types and reversed bounds return 422 invalid_query. Missing/mistyped source values do not match. Datetimes are normalized to UTC milliseconds (submillisecond digits are truncated).
        - object
          - `field` string, required
          - `any_of` union[], required: Exact equality (one value) or any-of equality. String-array fields match any element; values retain their declared type. Datetime equality uses RFC3339 strings.
            - union
              - …
          - `gte` string, date-time: Inclusive lower datetime bound. Requires a datetime field.
          - `lte` string, date-time: Inclusive upper datetime bound. Requires a datetime field.
        - object
          - `field` string, required
          - `any_of` union[]: Exact equality (one value) or any-of equality. String-array fields match any element; values retain their declared type. Datetime equality uses RFC3339 strings.
            - union
              - …
          - `gte` string, date-time, required: Inclusive lower datetime bound. Requires a datetime field.
          - `lte` string, date-time: Inclusive upper datetime bound. Requires a datetime field.
        - object
          - `field` string, required
          - `any_of` union[]: Exact equality (one value) or any-of equality. String-array fields match any element; values retain their declared type. Datetime equality uses RFC3339 strings.
            - union
              - …
          - `gte` string, date-time: Inclusive lower datetime bound. Requires a datetime field.
          - `lte` string, date-time, required: Inclusive upper datetime bound. Requires a datetime field.
  - `accepted_after` string, date-time: Inclusive current-Version acceptance-time lower bound, as in listing.
  - `accepted_before` string, date-time: Exclusive current-Version acceptance-time upper bound, as in listing.
  - `accuracy` 'exact' | 'fast': Absent or exact counts every current document now. fast is best effort: Quivr may answer sooner, usually within a few seconds, from stored snapshots (as_of), a uniform sample (approximate), or an exact count that ended within about a second (neither marker). The 25-second request deadline still applies.

## Response `200`

Bounded document counts and excluded Corpus explanations.

- FacetResponse
  - `items` Facet[], required
    - `field` string, required
    - `buckets` FacetBucket[], required
      - `value` union, required: Typed scalar value, array member, or RFC 3339 UTC date bucket start.
        - string
        - number, double
        - boolean
      - `count` integer, required
  - `excluded_corpora` CorpusExclusion[]
    - `corpus_id` string, required
    - `fields` string[], required
  - `as_of` string, date-time: Fast requests only. Counts come from stored per-Corpus snapshots, each exact when it was taken; this is the oldest snapshot's time. Changes since a Corpus's snapshot are missing from its counts, and newer snapshots of other Corpora include their later changes.
  - `approximate` boolean: Fast requests only; present and true when counts are estimates scaled from a uniform sample of Records.
  - `sample_fraction` number, double: Share of the Corpora's Records counted when approximate.

## Other responses

- `default`: Structured error; malformed_json, invalid_schema, request_too_large, unsupported_media_type, invalid_query, forbidden, not_found, metadata_filter_unavailable or content_unavailable.

---

[API](https://skmtc.dev/thevibecompany/apis/quivr-http-api.md) - [All operations](https://skmtc.dev/thevibecompany/apis/quivr-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thevibecompany/apis/quivr-http-api/revisions/4f4e30ba8f4e?raw)