> ## Documentation Index > Fetch the complete documentation index at: https://docs.quivr.thevibecompany.co/llms.txt > Use this file to discover all available pages before exploring further. # Count facets > 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. ## OpenAPI ````yaml /openapi.yaml post /v0/facets openapi: 3.1.0 info: title: Quivr HTTP API version: 0.0.0-draft description: >- Every endpoint of the Quivr v0 HTTP API. Send an API key as a bearer token; the key decides the Organization, the actions and the Corpora a request may reach. servers: [] security: - ApiKey: [] paths: /v0/facets: post: tags: - Facets summary: Count facets description: >- 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. operationId: countFacets requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FacetRequest' responses: '200': description: Bounded document counts and excluded Corpus explanations. content: application/json: schema: $ref: '#/components/schemas/FacetResponse' default: description: >- Structured error; malformed_json, invalid_schema, request_too_large, unsupported_media_type, invalid_query, forbidden, not_found, metadata_filter_unavailable or content_unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: FacetRequest: type: object additionalProperties: false required: - corpus_ids - fields properties: corpus_ids: type: array minItems: 1 maxItems: 16 uniqueItems: true items: type: string minLength: 1 fields: type: array minItems: 1 maxItems: 16 items: $ref: '#/components/schemas/FacetField' description: Distinct logical metadata field names, in response order. filter: $ref: '#/components/schemas/SearchFilter' accepted_after: type: string format: date-time description: >- Inclusive current-Version acceptance-time lower bound, as in listing. accepted_before: type: string format: date-time description: >- Exclusive current-Version acceptance-time upper bound, as in listing. FacetResponse: type: object additionalProperties: false required: - items properties: items: type: array maxItems: 16 items: $ref: '#/components/schemas/Facet' excluded_corpora: type: array maxItems: 16 items: $ref: '#/components/schemas/CorpusExclusion' Error: type: object additionalProperties: false properties: request_id: type: string description: Bounded caller X-Request-ID, or an engine-generated correlation ID. trace_id: type: string description: W3C trace ID when a trace context is present. span_id: type: string description: W3C span ID of the API handler when a trace context is present. code: type: string minLength: 1 message: type: string minLength: 1 retryable: type: boolean field: type: string minLength: 1 description: >- JSON Pointer (RFC 6901) to the request member that caused a 422, when known (for example /config/url or /credential/secret/token on connector commands). resync_url: type: string format: uri-reference required: - code - message - retryable FacetField: type: object additionalProperties: false required: - field properties: field: type: string pattern: ^(metadata\.)?[a-z][a-z0-9_]{0,63}$ limit: type: integer minimum: 1 maximum: 100 default: 20 interval: type: string enum: - day - month - year description: Required only for datetime fields; bucket start in UTC. SearchFilter: type: object additionalProperties: false minProperties: 1 properties: source_namespaces: type: array items: type: string minLength: 1 maxLength: 200 minItems: 1 maxItems: 50 uniqueItems: true description: >- 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: type: array minItems: 1 maxItems: 16 items: $ref: '#/components/schemas/MetadataFilter' description: >- 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). description: >- 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. Facet: type: object additionalProperties: false required: - field - buckets properties: field: type: string buckets: type: array maxItems: 100 items: $ref: '#/components/schemas/FacetBucket' CorpusExclusion: type: object additionalProperties: false properties: corpus_id: type: string fields: type: array items: type: string required: - corpus_id - fields description: >- Authorized Corpus excluded because these logical fields are not declared with the filter role. Common metadata fields are always declared. MetadataFilter: type: object additionalProperties: false properties: field: type: string pattern: ^(metadata\.)?[a-z][a-z0-9_]{0,63}$ any_of: type: array minItems: 1 maxItems: 50 items: anyOf: - type: string minLength: 1 maxLength: 200 - type: number x-go-type: float64 - type: boolean description: >- Exact equality (one value) or any-of equality. String-array fields match any element; values retain their declared type. Datetime equality uses RFC3339 strings. gte: type: string format: date-time description: Inclusive lower datetime bound. Requires a datetime field. lte: type: string format: date-time description: Inclusive upper datetime bound. Requires a datetime field. required: - field anyOf: - required: - any_of - required: - gte - required: - lte description: >- 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). FacetBucket: type: object additionalProperties: false required: - value - count properties: value: oneOf: - type: string - type: number format: double x-go-type: float64 - type: boolean description: Typed scalar value, array member, or RFC 3339 UTC date bucket start. count: type: integer format: int64 minimum: 1 securitySchemes: ApiKey: type: http scheme: bearer description: >- API key, not necessarily a JWT. Server derives Organization, permitted actions and Corpus scope; every resource access is authorized. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.