> ## Documentation Index > Fetch the complete documentation index at: https://api.visor.vin/docs/llms.txt > Use this file to discover all available pages before exploring further. # Filter facets > Returns categorical facets, numeric range facets, and stats for an explicit listing filter surface facet selection. Use facets=make,model,price. Supported facets: make, model, model_code, inventory_type, year, trim, version, base_exterior_color, exterior_color, base_interior_color, interior_color, seating_capacity, doors, engine, state, drivetrain, assembly_location, assembly_country, transmission, fuel_type, powertrain_type, body_type, cylinders, dealer_type, availability_status, options_packages, features, keywords, price, msrp, miles, days_on_market. ## OpenAPI ````yaml /openapi.json get /v1/facets openapi: 3.1.0 info: title: Visor Public API version: 1.0.0-beta summary: Vehicle listings, facets, VIN, and dealer data for API customers. description: >- Public beta API for customer integrations. Normal /v1 endpoints require Authorization: Bearer . API keys are scoped to API accounts; usage is metered per request and billed from the account ledger. The OpenAPI document is available without authentication at /v1/openapi.json. servers: - url: https://api.visor.vin description: Production public API security: - bearerAuth: [] tags: - name: Inventory - name: Dealers - name: Usage paths: /v1/facets: get: tags: - Inventory summary: Filter facets description: >- Returns categorical facets, numeric range facets, and stats for an explicit listing filter surface facet selection. Use facets=make,model,price. Supported facets: make, model, model_code, inventory_type, year, trim, version, base_exterior_color, exterior_color, base_interior_color, interior_color, seating_capacity, doors, engine, state, drivetrain, assembly_location, assembly_country, transmission, fuel_type, powertrain_type, body_type, cylinders, dealer_type, availability_status, options_packages, features, keywords, price, msrp, miles, days_on_market. operationId: publicInventory.facets parameters: - name: facets in: query schema: type: string description: >- Required comma-separated facet names to return. Supported facets: make, model, model_code, inventory_type, year, trim, version, base_exterior_color, exterior_color, base_interior_color, interior_color, seating_capacity, doors, engine, state, drivetrain, assembly_location, assembly_country, transmission, fuel_type, powertrain_type, body_type, cylinders, dealer_type, availability_status, options_packages, features, keywords, price, msrp, miles, days_on_market. required: true description: >- Required comma-separated facet names to return. Supported facets: make, model, model_code, inventory_type, year, trim, version, base_exterior_color, exterior_color, base_interior_color, interior_color, seating_capacity, doors, engine, state, drivetrain, assembly_location, assembly_country, transmission, fuel_type, powertrain_type, body_type, cylinders, dealer_type, availability_status, options_packages, features, keywords, price, msrp, miles, days_on_market. example: make,model,price - name: facet_value_limit in: query schema: type: string description: >- Maximum number of values returned per categorical facet. Defaults to 20; maximum 100. Numeric range facets always return fixed buckets. required: false description: >- Maximum number of values returned per categorical facet. Defaults to 20; maximum 100. Numeric range facets always return fixed buckets. example: '5' - name: metric in: query schema: type: string description: >- Facet Metric used to compute an optional per-bucket aggregate. Defaults to count. Supported measures: price, miles, msrp, days_on_market, discount_from_msrp. Supported aggregates: mean, p5, p25, median, p75, p95. Use ., for example price.p95 or days_on_market.median. Non-count metrics require exactly one categorical facet. required: false description: >- Facet Metric used to compute an optional per-bucket aggregate. Defaults to count. Supported measures: price, miles, msrp, days_on_market, discount_from_msrp. Supported aggregates: mean, p5, p25, median, p75, p95. Use ., for example price.p95 or days_on_market.median. Non-count metrics require exactly one categorical facet. - name: sort in: query schema: type: string enum: - count - '-count' - metric - '-metric' description: >- Facet bucket ordering. Defaults to -count. Sorting by metric requires a non-count metric. required: false description: >- Facet bucket ordering. Defaults to -count. Sorting by metric requires a non-count metric. - name: make in: query schema: type: string description: >- Comma-separated make names or slugs to apply before counting facet buckets. required: false description: >- Comma-separated make names or slugs to apply before counting facet buckets. example: Toyota - name: model in: query schema: type: string description: >- Comma-separated model names or slugs to apply before counting facet buckets. required: false description: >- Comma-separated model names or slugs to apply before counting facet buckets. - name: model_code in: query schema: type: string description: >- Comma-separated manufacturer model codes to apply before counting facet buckets. required: false description: >- Comma-separated manufacturer model codes to apply before counting facet buckets. - name: trim in: query schema: type: string description: Comma-separated trim names to apply before counting facet buckets. required: false description: Comma-separated trim names to apply before counting facet buckets. - name: year in: query schema: type: string description: >- Comma-separated model years to apply before counting facet buckets. required: false description: Comma-separated model years to apply before counting facet buckets. - name: state in: query schema: type: string description: >- Comma-separated two-letter dealer states to apply before counting facet buckets. required: false description: >- Comma-separated two-letter dealer states to apply before counting facet buckets. example: CA - name: dealer_id in: query schema: type: string description: >- Comma-separated dealer UUIDs to apply before counting facet buckets. Accepts up to 50 dealer IDs. required: false description: >- Comma-separated dealer UUIDs to apply before counting facet buckets. Accepts up to 50 dealer IDs. - name: dealer_type in: query schema: type: string description: >- Comma-separated dealer types to apply before counting facet buckets. required: false description: Comma-separated dealer types to apply before counting facet buckets. - name: availability_status in: query schema: type: string description: >- Comma-separated availability statuses to apply before counting facet buckets: stock, transit, build. required: false description: >- Comma-separated availability statuses to apply before counting facet buckets: stock, transit, build. - name: inventory_type in: query schema: type: string description: >- Comma-separated inventory classes to apply before counting facet buckets: new, used, certified. cpo is accepted as an alias for certified. required: false description: >- Comma-separated inventory classes to apply before counting facet buckets: new, used, certified. cpo is accepted as an alias for certified. - name: body_type in: query schema: type: string description: Comma-separated body types. required: false description: Comma-separated body types. - name: transmission in: query schema: type: string description: Comma-separated transmission values. required: false description: Comma-separated transmission values. - name: drivetrain in: query schema: type: string description: Comma-separated drivetrain values. required: false description: Comma-separated drivetrain values. - name: assembly_location in: query schema: type: string description: >- Pipe-separated assembly locations. Uses | because locations often contain commas. required: false description: >- Pipe-separated assembly locations. Uses | because locations often contain commas. - name: assembly_country in: query schema: type: string description: Comma-separated assembly country values. required: false description: Comma-separated assembly country values. - name: fuel_type in: query schema: type: string description: Comma-separated fuel type values. required: false description: Comma-separated fuel type values. - name: powertrain_type in: query schema: type: string description: Comma-separated powertrain type values. required: false description: Comma-separated powertrain type values. - name: engine in: query schema: type: string description: Comma-separated engine descriptions. required: false description: Comma-separated engine descriptions. - name: version in: query schema: type: string description: Comma-separated vehicle version values. required: false description: Comma-separated vehicle version values. - name: exterior_color in: query schema: type: string description: Comma-separated exterior color values. required: false description: Comma-separated exterior color values. - name: interior_color in: query schema: type: string description: Comma-separated interior color values. required: false description: Comma-separated interior color values. - name: base_exterior_color in: query schema: type: string description: Comma-separated normalized exterior color values. required: false description: Comma-separated normalized exterior color values. - name: base_interior_color in: query schema: type: string description: Comma-separated normalized interior color values. required: false description: Comma-separated normalized interior color values. - name: seating_capacity in: query schema: type: string description: Comma-separated seating capacity integers. required: false description: Comma-separated seating capacity integers. - name: cylinders in: query schema: type: string description: Comma-separated cylinder count integers. required: false description: Comma-separated cylinder count integers. - name: doors in: query schema: type: string description: Comma-separated door count integers. required: false description: Comma-separated door count integers. - name: options_packages in: query schema: type: string description: Comma-separated manufacturer option/package codes. required: false description: Comma-separated manufacturer option/package codes. - name: features in: query schema: type: string description: Comma-separated feature tokens. required: false description: Comma-separated feature tokens. - name: keywords in: query schema: type: string description: >- Comma-separated provenance/history keyword tokens to apply before counting facet buckets. Supported values: one_owner, clean_title, branded, fleet. required: false description: >- Comma-separated provenance/history keyword tokens to apply before counting facet buckets. Supported values: one_owner, clean_title, branded, fleet. - name: vin_pattern in: query schema: type: string description: >- Comma-separated VIN masks, up to 10 distinct patterns. VIN characters match themselves, ? matches one VIN position, and * is allowed only at the end. Short masks are treated as prefixes, for example 1HG or 1HGCM826*. required: false description: >- Comma-separated VIN masks, up to 10 distinct patterns. VIN characters match themselves, ? matches one VIN position, and * is allowed only at the end. Short masks are treated as prefixes, for example 1HG or 1HGCM826*. - name: exclude_make in: query schema: type: string description: Comma-separated makes to exclude. required: false description: Comma-separated makes to exclude. - name: exclude_model in: query schema: type: string description: Comma-separated models to exclude. required: false description: Comma-separated models to exclude. - name: exclude_trim in: query schema: type: string description: Comma-separated trims to exclude. required: false description: Comma-separated trims to exclude. - name: exclude_year in: query schema: type: string description: Comma-separated model years to exclude. required: false description: Comma-separated model years to exclude. - name: exclude_state in: query schema: type: string description: Comma-separated dealer states to exclude. required: false description: Comma-separated dealer states to exclude. - name: exclude_inventory_type in: query schema: type: string description: >- Comma-separated inventory classes to exclude: new, used, certified. cpo is accepted as an alias for certified. required: false description: >- Comma-separated inventory classes to exclude: new, used, certified. cpo is accepted as an alias for certified. - name: exclude_body_type in: query schema: type: string description: Comma-separated body types to exclude. required: false description: Comma-separated body types to exclude. - name: exclude_transmission in: query schema: type: string description: Comma-separated transmission values to exclude. required: false description: Comma-separated transmission values to exclude. - name: exclude_drivetrain in: query schema: type: string description: Comma-separated drivetrain values to exclude. required: false description: Comma-separated drivetrain values to exclude. - name: exclude_version in: query schema: type: string description: Comma-separated vehicle versions to exclude. required: false description: Comma-separated vehicle versions to exclude. - name: exclude_engine in: query schema: type: string description: Comma-separated engine descriptions to exclude. required: false description: Comma-separated engine descriptions to exclude. - name: exclude_assembly_location in: query schema: type: string description: >- Plus-separated assembly locations to exclude. Uses + to match the private API separator. required: false description: >- Plus-separated assembly locations to exclude. Uses + to match the private API separator. - name: exclude_assembly_country in: query schema: type: string description: Comma-separated assembly countries to exclude. required: false description: Comma-separated assembly countries to exclude. - name: exclude_exterior_color in: query schema: type: string description: Comma-separated exterior colors to exclude. required: false description: Comma-separated exterior colors to exclude. - name: exclude_interior_color in: query schema: type: string description: Comma-separated interior colors to exclude. required: false description: Comma-separated interior colors to exclude. - name: exclude_base_exterior_color in: query schema: type: string description: Comma-separated normalized exterior colors to exclude. required: false description: Comma-separated normalized exterior colors to exclude. - name: exclude_base_interior_color in: query schema: type: string description: Comma-separated normalized interior colors to exclude. required: false description: Comma-separated normalized interior colors to exclude. - name: exclude_options_packages in: query schema: type: string description: Comma-separated manufacturer option/package codes to exclude. required: false description: Comma-separated manufacturer option/package codes to exclude. - name: exclude_features in: query schema: type: string description: Comma-separated feature tokens to exclude. required: false description: Comma-separated feature tokens to exclude. - name: exclude_fuel_type in: query schema: type: string description: Comma-separated fuel types to exclude. required: false description: Comma-separated fuel types to exclude. - name: exclude_powertrain_type in: query schema: type: string description: Comma-separated powertrain types to exclude. required: false description: Comma-separated powertrain types to exclude. - name: exclude_keywords in: query schema: type: string description: Comma-separated keyword tokens to exclude. required: false description: Comma-separated keyword tokens to exclude. - name: inventory_status in: query schema: type: string enum: - active - sold description: Inventory mode used for facet counts. active is the default. required: false description: Inventory mode used for facet counts. active is the default. - name: listed_after in: query schema: type: string description: >- Filter to listings first observed by Visor on or after this ISO 8601 timestamp. required: false description: >- Filter to listings first observed by Visor on or after this ISO 8601 timestamp. - name: sold_within_days in: query schema: type: string description: Positive integer day window for sold inventory facets. required: false description: Positive integer day window for sold inventory facets. - name: snapshot_date in: query schema: type: string description: Historical active-inventory snapshot date in YYYY-MM-DD format. required: false description: Historical active-inventory snapshot date in YYYY-MM-DD format. - name: min_price in: query schema: type: string description: Minimum listed price in whole dollars. required: false description: Minimum listed price in whole dollars. - name: max_price in: query schema: type: string description: Maximum listed price in whole dollars. required: false description: Maximum listed price in whole dollars. - name: min_mileage in: query schema: type: string description: Minimum odometer mileage. required: false description: Minimum odometer mileage. - name: max_mileage in: query schema: type: string description: Maximum odometer mileage. required: false description: Maximum odometer mileage. - name: min_msrp in: query schema: type: string description: Minimum combined MSRP in whole dollars. required: false description: Minimum combined MSRP in whole dollars. - name: max_msrp in: query schema: type: string description: Maximum combined MSRP in whole dollars. required: false description: Maximum combined MSRP in whole dollars. - name: min_days_on_market in: query schema: type: string description: Minimum days on market. required: false description: Minimum days on market. - name: max_days_on_market in: query schema: type: string description: Maximum days on market. required: false description: Maximum days on market. - name: latitude in: query schema: type: string description: Search origin latitude for radius filtering. required: false description: Search origin latitude for radius filtering. - name: longitude in: query schema: type: string description: Search origin longitude for radius filtering. required: false description: Search origin longitude for radius filtering. - name: postal_code in: query schema: type: string description: US ZIP/postal search origin for radius filtering. required: false description: US ZIP/postal search origin for radius filtering. - name: radius in: query schema: type: string description: >- Maximum distance from the search origin, in miles. Requires postal_code or latitude and longitude. Maximum 500. required: false description: >- Maximum distance from the search origin, in miles. Requires postal_code or latitude and longitude. Maximum 500. - name: bbox in: query schema: type: string description: >- Map viewport as west,south,east,north. Cannot be combined with radius. Maximum diagonal is 1000 miles. required: false description: >- Map viewport as west,south,east,north. Cannot be combined with radius. Maximum diagonal is 1000 miles. responses: '200': description: Successful public API response. content: application/json: schema: type: object properties: data: type: object properties: total: type: number description: Total matching records for the supplied filters. facets: type: object additionalProperties: type: array items: type: object properties: value: type: string description: Facet value. count: type: number description: Number of matching records for the value. metric: type: object properties: name: type: string description: >- Selected Facet Metric name, for example price.p95. value: anyOf: - type: number - type: 'null' description: >- Facet Metric value, or null when suppressed by the minimum sample-size rule. null_reason: type: string enum: - insufficient_sample description: Reason the Facet Metric value is null. required: - name - value additionalProperties: false description: >- Selected non-count Facet Metric for this bucket. name: type: string description: >- Display name for enriched option package buckets. msrp: anyOf: - type: number - type: 'null' description: >- Median MSRP for enriched option package buckets when available. avg_price: type: number description: >- Median listed price for this bucket when option sort enrichment is enabled internally. avg_days_on_lot: type: number description: >- Median days on lot for this bucket when option sort enrichment is enabled internally. avg_discount: type: number description: >- Median discount from MSRP for this bucket when option sort enrichment is enabled internally. required: - value - count additionalProperties: false description: Facet value bucket. description: >- Categorical facet buckets keyed by facet name, ordered by count descending. range_facets: type: object additionalProperties: type: object properties: buckets: type: array items: type: object properties: min: type: number description: >- Inclusive lower bound for this numeric bucket. max: type: number description: >- Exclusive upper bound for this numeric bucket. count: type: number description: Number of matching records in the bucket. required: - min - max - count additionalProperties: false description: Numeric facet bucket. description: Numeric buckets ordered by min ascending. interval: anyOf: - type: number - type: 'null' description: Bucket width when available. min: type: number description: Smallest returned bucket lower bound. max: type: number description: Largest returned bucket upper bound. required: - buckets - interval - min - max additionalProperties: false description: Numeric range facet. description: Numeric facet buckets keyed by facet name. stats: type: object additionalProperties: type: object properties: min: type: number description: Minimum value for the matching records. max: type: number description: Maximum value for the matching records. count: type: number description: >- Number of matching records with a non-null value. missing: type: number description: Number of matching records missing this value. mean: type: number description: Mean value for the matching records. median: type: number description: Median value for the matching records. stddev: type: number description: >- Sample standard deviation for the matching records. required: - min - max - count - missing - mean - median - stddev additionalProperties: false description: Stats for a numeric facet field. description: Numeric stats keyed by range facet name. required: - total - facets - range_facets - stats additionalProperties: false description: Facet counts and numeric ranges for the supplied filters. meta: type: object properties: facets: type: array items: type: string description: >- Facet names requested and returned, after default expansion. metric: type: string description: >- Facet Metric used for this response. Defaults to count. sort: type: string enum: - count - '-count' - metric - '-metric' description: Facet bucket ordering used for this response. minimum_metric_count: type: number description: >- Minimum bucket count required before non-count metric values are returned. Currently 10. required: - facets - metric - sort - minimum_metric_count additionalProperties: false description: Facet response metadata. required: - data - meta additionalProperties: false description: Facet response envelope. examples: success: summary: >- Make, model, and price facets for Toyota inventory in California value: data: total: 62152 facets: make: - value: Toyota count: 62152 model: - value: Camry count: 13730 - value: Tacoma count: 10682 - value: RAV4 count: 7499 range_facets: price: buckets: - min: 24608 max: 28732 count: 5270 - min: 28732 max: 32856 count: 5528 - min: 32856 max: 36980 count: 8392 interval: 4124 min: 3988 max: 86468 stats: price: min: 0 max: 148085 count: 60556 missing: 1596 mean: 38889.62 median: 38300 stddev: 15641.34 meta: facets: - make - model - price metric: count sort: '-count' minimum_metric_count: 10 headers: X-Usage-Class: description: >- Metering class used for the request, for example listing_search, listing_search_enriched, facet_counts_historical, vehicle_detail_enriched, or dealer_lookup. schema: type: string X-Usage-Cost-Micros: description: >- Usage cost for this request in integer USD micros. 1000000 micros equals 1 USD. schema: type: string X-Pricing-Version: description: Pricing catalog version UUID used to calculate the request cost. schema: type: string X-RateLimit-Tier: description: Effective account Usage Tier code used for rate limiting. schema: type: string X-RateLimit-Limit-10s: description: Maximum requests allowed in the 10-second burst window. schema: type: string X-RateLimit-Remaining-10s: description: >- Remaining requests in the current 10-second burst window after this request. schema: type: string X-RateLimit-Limit-60s: description: Maximum requests allowed in the 60-second sustained window. schema: type: string X-RateLimit-Remaining-60s: description: >- Remaining requests in the current 60-second sustained window after this request. schema: type: string '400': description: >- Invalid path or query parameter. Unknown query parameters are rejected. content: application/json: schema: $ref: '#/components/schemas/PublicApiValidationError' '401': description: Missing, malformed, or invalid Authorization bearer token. content: application/json: schema: $ref: '#/components/schemas/PublicApiAuthenticationError' '402': description: The API account is blocked by billing state or prepaid balance. content: application/json: schema: $ref: '#/components/schemas/PublicApiBillingError' '403': description: The API key is valid but does not include the required scope. content: application/json: schema: $ref: '#/components/schemas/PublicApiPermissionError' '429': description: >- The API account exceeded the public API rate limit. Retry-After is included when available. content: application/json: schema: $ref: '#/components/schemas/PublicApiRateLimitError' '503': description: >- The platform could not price, meter, rate-limit, or fetch data for the request. content: application/json: schema: $ref: '#/components/schemas/PublicApiPlatformError' security: - bearerAuth: [] components: schemas: PublicApiValidationError: type: object properties: _tag: type: string enum: - PublicApiValidationError error: type: object properties: type: type: string code: type: string message: type: string current_version: anyOf: - type: string - type: 'null' minimum_supported_version: anyOf: - type: string - type: 'null' reason_code: anyOf: - type: string - type: 'null' update_url: type: string update_command: type: string required: - type - code - message additionalProperties: false required: - _tag - error additionalProperties: false PublicApiAuthenticationError: type: object properties: _tag: type: string enum: - PublicApiAuthenticationError error: type: object properties: type: type: string code: type: string message: type: string current_version: anyOf: - type: string - type: 'null' minimum_supported_version: anyOf: - type: string - type: 'null' reason_code: anyOf: - type: string - type: 'null' update_url: type: string update_command: type: string required: - type - code - message additionalProperties: false required: - _tag - error additionalProperties: false PublicApiBillingError: type: object properties: _tag: type: string enum: - PublicApiBillingError error: type: object properties: type: type: string code: type: string message: type: string current_version: anyOf: - type: string - type: 'null' minimum_supported_version: anyOf: - type: string - type: 'null' reason_code: anyOf: - type: string - type: 'null' update_url: type: string update_command: type: string required: - type - code - message additionalProperties: false required: - _tag - error additionalProperties: false PublicApiPermissionError: type: object properties: _tag: type: string enum: - PublicApiPermissionError error: type: object properties: type: type: string code: type: string message: type: string current_version: anyOf: - type: string - type: 'null' minimum_supported_version: anyOf: - type: string - type: 'null' reason_code: anyOf: - type: string - type: 'null' update_url: type: string update_command: type: string required: - type - code - message additionalProperties: false required: - _tag - error additionalProperties: false PublicApiRateLimitError: type: object properties: _tag: type: string enum: - PublicApiRateLimitError error: type: object properties: type: type: string code: type: string message: type: string current_version: anyOf: - type: string - type: 'null' minimum_supported_version: anyOf: - type: string - type: 'null' reason_code: anyOf: - type: string - type: 'null' update_url: type: string update_command: type: string required: - type - code - message additionalProperties: false retryAfter: type: number required: - _tag - error additionalProperties: false PublicApiPlatformError: type: object properties: _tag: type: string enum: - PublicApiPlatformError error: type: object properties: type: type: string code: type: string message: type: string current_version: anyOf: - type: string - type: 'null' minimum_supported_version: anyOf: - type: string - type: 'null' reason_code: anyOf: - type: string - type: 'null' update_url: type: string update_command: type: string required: - type - code - message additionalProperties: false required: - _tag - error additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: >- Send API keys as Authorization: Bearer . Query-string API keys are rejected. ````