> ## Documentation Index > Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt > Use this file to discover all available pages before exploring further. # List the filterable facet values a set of findings carries, with counts > One GROUP BY over the derived facet index, not one query per value. This is the surface that makes a filter panel correct at estate scale: the review workspace filters a client-side array capped at 5,000 findings while printing the server's true total beside it, so on a real project the filter narrows a truncated set and the count describes a different one. Counts are computed over the population the SAME narrowing parameters would return from GET /v1/findings, so a value's count is exactly how many findings selecting it would show. The `facet` selection is applied disjunctively: a path's values are counted over the population narrowed by every OTHER selected path, never by its own. Selecting one licence therefore leaves the other licences' counts where they were, so the dropdown still offers the values that widen the selection, while every other path narrows to the selection. ## OpenAPI ````yaml /api-reference/earnie/triage-openapi.json get /v1/findings/facets openapi: 3.0.3 info: title: Earnie Findings API description: List and read findings, triage them, and review resolutions. version: 1.0.0 servers: - url: https://{tenant}.earnie.dev description: Your Earnie deployment variables: tenant: default: your-company description: >- Your organization's Earnie address, as shown in your browser when you sign in. security: - bearerAuth: [] paths: /v1/findings/facets: get: tags: - findings summary: List the filterable facet values a set of findings carries, with counts description: >- One GROUP BY over the derived facet index, not one query per value. This is the surface that makes a filter panel correct at estate scale: the review workspace filters a client-side array capped at 5,000 findings while printing the server's true total beside it, so on a real project the filter narrows a truncated set and the count describes a different one. Counts are computed over the population the SAME narrowing parameters would return from GET /v1/findings, so a value's count is exactly how many findings selecting it would show. The `facet` selection is applied disjunctively: a path's values are counted over the population narrowed by every OTHER selected path, never by its own. Selecting one licence therefore leaves the other licences' counts where they were, so the dropdown still offers the values that widen the selection, while every other path narrows to the selection. operationId: GetV1FindingsFacets parameters: - name: org_id in: query required: false description: >- Optional. Defaults to the authenticated principal's organization. When supplied it MUST match the caller's org (else 403). schema: type: string format: uuid - name: project_id in: query required: false schema: type: string format: uuid - name: state in: query required: false description: >- One of open, assigned, resolved, superseded_by_rule, reopened, as GET /v1/findings' own `state` filter accepts it. An unrecognised value is rejected with 400 rather than ignored, for the same reason an unrecognised facet path is. Not declared as an inline `enum` deliberately. oapi-codegen names a generated enum constant by its bare value unless another enum in the same document shares it, so repeating these five values here renames the constants of unrelated operations that happen to share one. The vocabulary is findings/domain.State either way, and this endpoint checks against it directly. schema: type: string - name: domain_slug in: query required: false description: Narrow to one producing scanner, as on GET /v1/findings. schema: type: string - name: scan_id in: query required: false schema: type: string format: uuid - name: path_prefix in: query required: false description: >- Same exact-path-or-subtree match as GET /v1/findings. Do NOT pass a trailing slash. schema: type: string - name: purl in: query required: false schema: type: string - name: facet in: query required: false description: >- The current selection, counted disjunctively (see above). The same `:` vocabulary and validation as GET /v1/findings' `facet`: values of one path are OR-ed, paths are AND-ed, and an unrecognised or non-entitled path is rejected with 400. schema: type: array items: type: string style: form explode: true - name: q in: query required: false description: >- Free-text SUBSEQUENCE search over a finding's path, purl, basename and title: the exact haystack and matcher of GET /v1/findings/files' `q`, so a count here equals the number of findings that list aggregates for the same query. schema: type: string - name: domain in: query required: false description: >- Narrow to one product finding family (oss, deps, crypto, ai, provenance), as GET /v1/findings' `domain`. Unknown values are ignored (no filter applied), exactly as GET /v1/findings ignores them, so the counts keep describing the list. Not declared as an inline `enum`, for the reason `state` above gives. schema: type: string - name: path in: query required: false description: >- Restrict the response to these facet paths. Repeatable. Omitted returns every path the narrowed population carries and this organization is entitled to see. An unrecognised path is rejected with 400, for the same reason the list filter rejects one. schema: type: array items: type: string style: form explode: true - name: limit in: query required: false description: >- Maximum values per facet path, ordered by count descending then value ascending. A path with more sets `truncated`, so a caller can tell a short list from a complete one. Out-of-range values fall back to the default. schema: type: integer default: 100 maximum: 1000 responses: '200': description: The facet values the narrowed findings carry content: application/json: schema: $ref: '#/components/schemas/FindingFacetListResponse' '400': description: Invalid query parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Insufficient permissions (findings:read required) content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: FindingFacetListResponse: type: object required: - facets properties: facets: type: array items: $ref: '#/components/schemas/FindingFacet' Error: type: object required: - code - message properties: code: type: string message: type: string FindingFacet: type: object required: - path - values - truncated properties: path: type: string description: >- The facet's address, which is the policy field catalog's own path for the same fact ("crypto.mode" is what a policy expression reads as finding.crypto.mode). A path this organization is not entitled to is absent from the response rather than empty, so the list never advertises a vocabulary the caller cannot use. example: crypto.mode values: type: array items: $ref: '#/components/schemas/FindingFacetValue' truncated: type: boolean description: True when this path carries more values than `limit` returned. FindingFacetValue: type: object required: - value - count properties: value: type: string example: cbc count: type: integer description: How many of the narrowed findings carry this value at this path. securitySchemes: bearerAuth: type: http scheme: bearer description: >- An Earnie API key, sent as `Authorization: Bearer sk_earnie_...`. Create one under Settings > API keys. The key's scopes decide which operations it may call. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.