> ## Documentation Index > Fetch the complete documentation index at: https://docs.getjumper.io/llms.txt > Use this file to discover all available pages before exploring further. # Get metadata filter facets > Returns curated metadata filter facets and coverage for a searchable scope. Call this before search to render available filter options, then pass selected filters to visual or transcript search using `metadata_filter_request`. For `mode: global`, facets are scoped to loaded searchable media for the requested `media_type`, not every row in the local metadata database. ## OpenAPI ````yaml /api-reference/openapi-v1.yaml post /metadata/facets openapi: 3.0.3 info: title: Jumper Public API version: '1.0' description: > REST API for third-party integrations with Jumper's media analysis engine. Jumper analyzes video, image, and audio files — enabling semantic visual search, speech transcription, and face detection with clustering. This API exposes those capabilities for use by MAM systems, automation pipelines, and custom tooling. ## Authentication All endpoints except `/health` require a **Jumper Pro** license key. The OpenAPI contract models the supported `X-License-Key` header flow. Jumper also accepts a `license_key` field in many JSON POST bodies as a convenience, but that is a Jumper-specific request-body convention rather than an OpenAPI security scheme. Invalid or missing keys return `401`. Non-Pro keys return `403`. ## Key Concepts - **`cache_dir`** — The folder where Jumper stores analysis data (visual analysis, transcriptions, face clusters). You choose this path. - **`media_paths`** — Absolute filesystem paths to media files. Jumper needs direct access to these files. - **`hash_str`** — A CRC32-based hash that uniquely identifies a media file. Returned by the metadata endpoint. - **`model_key`** — Internal identifier for a visual or speech analysis model variant (e.g. `v2-medium-256`). contact: name: Jumper url: https://getjumper.io servers: - url: http://localhost:6699/api/v1 description: Local Jumper backend security: - HeaderAuth: [] paths: /metadata/facets: post: tags: - Metadata Filters summary: Get metadata filter facets description: > Returns curated metadata filter facets and coverage for a searchable scope. Call this before search to render available filter options, then pass selected filters to visual or transcript search using `metadata_filter_request`. For `mode: global`, facets are scoped to loaded searchable media for the requested `media_type`, not every row in the local metadata database. requestBody: required: true content: application/json: schema: type: object required: - cache_dir properties: cache_dir: type: string scope: $ref: '#/components/schemas/MetadataFilterScope' media_type: type: string enum: - visual - speech - any default: any description: Used when `scope` is omitted. media_paths: type: array items: type: string description: Used to build a path scope when `scope` is omitted. hash_strs: type: array items: type: string description: Hashes aligned with `media_paths` when `scope` is omitted. search_all: type: boolean default: false description: Build a global scope when `scope` is omitted. expected_count: type: integer description: >- Optional count used for coverage reporting when `scope` is omitted. filters: type: array items: $ref: '#/components/schemas/MetadataFilter' default: [] description: >- Usually empty for option loading. Included only for active-filter count reporting. responses: '200': description: Metadata facets and coverage content: application/json: schema: $ref: '#/components/schemas/MetadataFacetResponse' components: schemas: MetadataFilterScope: type: object properties: mode: type: string enum: - paths - global default: paths description: >- `paths` scopes filters to the supplied files; `global` scopes to loaded searchable media. media_type: type: string enum: - visual - speech - any default: any description: Searchable media type for the scope. media_paths: type: array items: type: string description: >- Absolute media paths. When paired with `hash_strs`, the arrays are index-aligned. hash_strs: type: array items: type: string description: >- Media hashes aligned with `media_paths`, or standalone hashes for already-known media. expected_count: type: integer description: Optional count used for coverage reporting. MetadataFilter: type: object required: - facet_id - values properties: facet_id: type: string description: >- Facet identifier returned by `/metadata/facets`, such as `video.codec`. operator: type: string enum: - is_any_of - is_not - include_any_of - include_all_of - exclude_any_of - exclude_all_of - before - after - greater_than - less_than default: is_any_of values: type: array items: type: string description: Selected facet option values. MetadataFacetResponse: type: object properties: success: type: boolean facets: type: array items: $ref: '#/components/schemas/MetadataFacet' coverage: $ref: '#/components/schemas/MetadataCoverage' active_filter_count: type: integer warning: type: string nullable: true MetadataFacet: type: object properties: id: type: string example: video.codec label: type: string example: Codec group: type: string example: Video path: type: array items: type: string kind: type: string enum: - single - multi - numeric - date options: type: array items: $ref: '#/components/schemas/MetadataFacetOption' min: oneOf: - type: number - type: string max: oneOf: - type: number - type: string MetadataCoverage: type: object properties: scope_count: type: integer description: Number of files or hashes in the requested scope. indexed_count: type: integer description: Number of scoped files that currently have indexed metadata. missing_count: type: integer description: Number of scoped files without indexed metadata. MetadataFacetOption: type: object properties: value: type: string label: type: string count: type: integer meta: type: object additionalProperties: true securitySchemes: HeaderAuth: type: apiKey in: header name: X-License-Key description: Jumper Pro license key passed via header ````