Get Live Vehicle by VIN

GET /v1/vehicles/vin/{vin}/live Every other vehicle endpoint answers from the last import. This one goes to the dealer’s website while you wait and returns what it says right now. Use it when staleness is the problem you are solving — a shopper on the phone, a price you are about to quote, a listing you suspect has sold.

A live call is slower and more expensive than a cached read. It is not a replacement for the feed: use the feed for breadth, this for the one VIN that matters this second. If you need a handful of VINs warm before a customer conversation, prewarm them with POST /v1/sessions instead of calling this endpoint in a loop.

Two ways to address a dealer

you send	path taken	what you get
`dealership_id`	stored-row path — the dealer’s saved import configuration	the full record, including the price breakdown
`dealer_url` only	un-onboarded path — the dealer is discovered from their homepage	price and specification; the breakdown depends on the platform
neither	the VIN is resolved across every active dealer on your account	a `matches` array, one entry per rooftop that has it

dealership_id wins if you send both. A dealer_url whose host is already one of your active, configured dealers is treated as that dealer — you do not get a second, worse answer for a rooftop you have onboarded.

Query parameters

name	type	default	notes
`dealership_id`	integer	—	optional. Omit to search all your active dealers.
`dealer_url`	string	—	optional. The un-onboarded entry point. Host or full URL.
`source`	string	`dealer_website`	reserved; only `dealer_website` is served today.
`fresh`	boolean	`false`	`true` bypasses the prewarm store and the discovery cache and forces a new fetch.

Outcomes

The source field is the answer to “did we get this from the dealer just now?”. Read it before you read the price.

`source`	meaning	act on it how
`live`	fetched from the dealer’s site during this request	trust it
`prewarmed`	served from a session you warmed earlier	trust it; check `observed_at` for age
`gone`	the dealer’s own system says it does not have this VIN	treat the listing as withdrawn
`cached`	we could not reach a conclusion; the payload carries the last known values	fall back, and read `cached_reason`
`unsupported`	un-onboarded path only: we identified the platform and cannot serve it live	use the feed

cached is never a price you should quote as current. It means the fetch failed, not that the car is unchanged.

`cached_reason`

reason	what happened
`timeout`	the dealer did not answer inside the tier deadline
`fetch_failed`	the connection failed outright
`http_error`	a non-200 that is not a withdrawal (403, 500, 502…)
`vin_not_in_body`	the dealer answered, but the response was for a different VIN
`no_parser`	we have no reader for this platform, or the config cannot build a call
`dealer_unhealthy`	this dealer’s circuit breaker is open after repeated failures
`host_busy`	the per-host rate limit would have been breached
`not_in_scope`	outside the covered region
`ids_unresolved`	DealerOn only: its `(dealerId, pageId)` discovery did not finish in time. The next call is warm.
`locator_timeout`, `locator_blocked`, `locator_error`	un-onboarded VDP-parser platforms: the page locator could not find the VIN’s page
`walk_incomplete`	iManPro only: the listing walk ran out of deadline. The VIN may still be listed — never read this as gone.
`no_price_in_jsonld`	the VDP publishes a schema.org block for this VIN with no `offers`, so there is no price in it

`gone_confirmed`

On the un-onboarded path a gone carries gone_confirmed. A cached provider id that has gone stale looks identical to a sold car on several platforms, so before returning gone we ask the same ids, unfiltered, whether they can see any inventory. true means that check passed and the withdrawal is real. false means we could not complete the check — the listing is probably gone, but it is not confirmed.

Provenance fields

Two fields tell you where the numbers came from. They exist because a live fetch can succeed and still be missing something the stored row has.

field	values	meaning
`price_source`	`live` · `stored`	`stored` means the fetch produced no usable price and the last known one was carried, or a carried breakdown corrected it
`breakdown_source`	`live` · `stored` · `none`	`none` means this platform’s live endpoint carries no itemised prices at all
`breakdown_reason`	e.g. `no_breakdown_on_api`	present when `breakdown_source` is `none`

breakdown_source: "none" is not cosmetic. On some platforms the dealer’s live API omits a documentation fee that the dealer’s own website displays, so a live-only price can be lower than the advertised price. Where we have a stored breakdown we carry it and report breakdown_source: "stored"; where we do not, the price may exclude dealer fees and breakdown_reason says so.

The `vehicle` object is shaped differently here

On this endpoint price_components and photo_url_list are returned as native JSON objects and arrays. On the feed endpoints — Get Vehicle by VIN, Search Vehicles — the same fields are returned as JSON strings that you have to parse.So JSON.parse(vehicle.price_components) works against the feed and throws against this endpoint. Check the type, or branch on which endpoint you called.

Every other field follows the vehicle schema, including fees_included_in_final and fee_total_from_components.

Latency by tier

tier is how the dealer’s platform has to be reached. It sets the deadline.

tier	route	deadline	typical
`A`	direct, no proxy	2 s	20–350 ms warm, up to ~1 s cold
`B`	through the unblocking tunnel	4 s	1–3 s

Add roughly 300 ms–1 s the first time you ask about an un-onboarded dealer: their homepage has to be fetched and the platform identified. That result is cached per host for 7 days, so the second call is as fast as an onboarded one. fresh=true pays the cold cost every time, by design. The deadline is applied to the request itself, so a slow dealer costs you the deadline and no more.

Examples

Onboarded, `source: live`

curl "https://api.autosnap.com/v1/vehicles/vin/5YM33CS04V9600257/live?dealership_id=2119&fresh=true" \
  -H "X-API-Key: $AUTOSNAP_API_KEY"

{
  "success": true,
  "source": "live",
  "vin": "5YM33CS04V9600257",
  "dealership_id": 2119,
  "provider": "CarsCommerce",
  "observed_at": "2026-09-24T15:18:03Z",
  "vdp_link": "https://www.bmwofriverside.com/inventory/new-2027-bmw-xm-label-awd-4d-sport-utility-5ym33cs04v9600257/",
  "tier": "A",
  "fetch_ms": 94,
  "http_status": 200,
  "breakdown_source": "live",
  "price_source": "live",
  "vehicle": {
    "vin": "5YM33CS04V9600257",
    "price": 163822,
    "msrp": 163700,
    "final_price": 163822,
    "total_fees": 122,
    "total_discounts": 0,
    "fees_included_in_final": true,
    "fee_total_from_components": 122,
    "price_components": {
      "components": [
        { "type": "msrp",                       "label": "MSRP",                       "amount": 163700, "category": "starting" },
        { "type": "documentation_fee",          "label": "Dealer Documentation Fee",    "amount": 85,     "category": "fee" },
        { "type": "dealer_fee",                 "label": "Electronic Filing Fee",       "amount": 37,     "category": "fee" },
        { "type": "net_price_with_dealer_fees", "label": "Total Price",                 "amount": 163822, "category": "final" }
      ]
    }
  }
}

fetch_ms: 94 is the dealer’s own response time; the rest of the 674 ms round trip is our gates and your network.

Un-onboarded, `source: live`

A dealer you have never onboarded, addressed by URL. Note dealership_id: null, the dealer block describing what we found, and breakdown_source: "none".

curl "https://api.autosnap.com/v1/vehicles/vin/1N4AL3AP7FC583737/live?dealer_url=https://3riversvw.com&fresh=true" \
  -H "X-API-Key: $AUTOSNAP_API_KEY"

{
  "success": true,
  "vin": "1N4AL3AP7FC583737",
  "dealership_id": null,
  "dealer": {
    "url": "https://www.3riversvw.com",
    "host": "3riversvw.com",
    "provider": "TeamVelocity",
    "resolved": "detected",
    "ids_cached": false,
    "tunnel_used": false
  },
  "provider": "TeamVelocity",
  "source": "live",
  "tier": "A",
  "observed_at": "2026-09-24T15:18:06Z",
  "fetch_ms": 107,
  "http_status": 200,
  "breakdown_source": "none",
  "breakdown_reason": "no_breakdown_on_api",
  "price_suspect": false,
  "vehicle": { "vin": "1N4AL3AP7FC583737", "price": 8789 }
}

resolved is detected on a cold call and cached once the host is known. tunnel_used tells you whether the discovery fetch needed the unblocking tunnel.

`source: gone`

{
  "success": true,
  "vin": "1HGCV1F30LA900001",
  "dealership_id": null,
  "dealer": {
    "url": "https://www.3riversvw.com",
    "host": "3riversvw.com",
    "provider": "TeamVelocity",
    "resolved": "cached",
    "ids_cached": true,
    "tunnel_used": false
  },
  "provider": "TeamVelocity",
  "source": "gone",
  "gone_reason": "not_in_dealer_api",
  "gone_confirmed": true,
  "observed_at": "2026-09-24T15:18:09Z",
  "http_status": 200,
  "fetch_ms": 88
}

`source: prewarmed`

The same VIN immediately after a session warmed it. observed_at is when the warming fetch saw it, not when you asked — you are being told the age of the data.

{
  "success": true,
  "source": "prewarmed",
  "prewarmed_source": "live",
  "vin": "5YM33CS04V9600257",
  "dealership_id": 2119,
  "provider": "CarsCommerce",
  "observed_at": "2026-09-24T15:18:12Z",
  "breakdown_source": "live",
  "price_source": "live",
  "fetch_ms": 108
}

Errors

status	code	when
`404`	—	the VIN is not on any of your active dealers (stored-row path)
`422`	`DEALER_URL_INVALID`	`dealer_url` has no readable hostname
`422`	`DEALER_NOT_DETECTED`	we reached the site and could not identify the platform
`422`	`DEALER_UNREACHABLE`	the host did not resolve or did not answer
`422`	`REGION_NOT_COVERED`	outside the covered region
`429`	—	rate limited; see Rate Limits

The un-onboarded path is metered separately from this endpoint’s own class, because discovery costs us a homepage fetch on top of the VIN call.

API Reference

Dealers

Inventory

Semantic Search

Feed Management

Webhooks

Account

Two ways to address a dealer

Query parameters

Outcomes

`cached_reason`

`gone_confirmed`

Provenance fields

The `vehicle` object is shaped differently here

Latency by tier

Examples

Onboarded, `source: live`

Un-onboarded, `source: live`

`source: gone`

`source: prewarmed`

Errors

​Two ways to address a dealer

​Query parameters

​Outcomes

​cached_reason

​gone_confirmed

​Provenance fields

​The vehicle object is shaped differently here

​Latency by tier

​Examples

​Onboarded, source: live

​Un-onboarded, source: live

​source: gone

​source: prewarmed

​Errors

Two ways to address a dealer

Query parameters

Outcomes

`cached_reason`

`gone_confirmed`

Provenance fields

The `vehicle` object is shaped differently here

Latency by tier

Examples

Onboarded, `source: live`

Un-onboarded, `source: live`

`source: gone`

`source: prewarmed`

Errors