> ## 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.

# Common Examples

> Copyable Public API workflows for vehicle searches, facets, dealer inventory, and usage.

These examples assume:

```sh theme={null}
export VISOR_API_KEY="vis_live_..."
```

## Newest Toyota Camry listings in California

```sh theme={null}
curl "https://api.visor.vin/v1/listings?make=Toyota&model=Camry&state=CA&limit=10&fields=default,price,miles,dealer_name,vdp_url" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Use `pagination.next_offset` to fetch the next page:

```sh theme={null}
curl "https://api.visor.vin/v1/listings?make=Toyota&model=Camry&state=CA&limit=10&offset=10&fields=default,price,miles,dealer_name,vdp_url" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

## Discover exact model names

```sh theme={null}
curl "https://api.visor.vin/v1/facets?facets=model&make=Ford&facet_value_limit=100" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Use the returned values, such as `F-150`, in listing searches.

## Compare trims by median price

```sh theme={null}
curl "https://api.visor.vin/v1/facets?facets=trim&make=Ford&model=F-150&metric=price.median&sort=-metric&facet_value_limit=20" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Facet metrics still return `count` for sample-size context. Buckets with fewer than 10 matching listings return `metric.value: null`.

## Search near a ZIP code

```sh theme={null}
curl "https://api.visor.vin/v1/listings?make=Honda&model=Civic&postal_code=98101&radius=100&sort=distance&limit=10&fields=default,price,miles,distance_miles,dealer_name,vdp_url" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

`sort=distance` requires `postal_code` or `latitude` and `longitude`.

## Sold RAV4 listings from the last 30 days

```sh theme={null}
curl "https://api.visor.vin/v1/listings?make=Toyota&model=RAV4&inventory_status=sold&sold_within_days=30&limit=25&fields=default,price,miles,sold_date,dealer_name" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Add `include=price_history` when you need observed price changes:

```sh theme={null}
curl "https://api.visor.vin/v1/listings?make=Toyota&model=RAV4&inventory_status=sold&sold_within_days=30&limit=10&fields=default,price,miles,sold_date&include=price_history" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Enriched listing search pricing applies when `include=price_history` or `include=options` is requested.

## Decode a VIN with options and price history

```sh theme={null}
curl "https://api.visor.vin/v1/vins/1HGCM82633A004352?include=price_history,options" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Unknown VINs return `404 not_found_error`; known VINs can return `status: "missing"` when they no longer appear in active inventory but have not been classified as sold.

## Find franchise Toyota dealers in California

```sh theme={null}
curl "https://api.visor.vin/v1/dealers?state=CA&type=franchise&make=Toyota&limit=10" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Then list attributed inventory for one dealer:

```sh theme={null}
curl "https://api.visor.vin/v1/dealers/00000000-0000-0000-0000-000000000000/listings?limit=10" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Dealer inventory is deduplicated by VIN and assigned to the dealer Visor believes owns the listing.

## Check account usage

```sh theme={null}
curl "https://api.visor.vin/v1/usage?start_date=2026-05-01&end_date=2026-05-31" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

Filter to selected metering classes:

```sh theme={null}
curl "https://api.visor.vin/v1/usage?metering_class=listing_search,vehicle_detail" \
  -H "Authorization: Bearer $VISOR_API_KEY"
```

`/v1/usage` requires `usage.read`, is not billable, and is eventually consistent with the billing ledger.