> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosnap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Live Vehicle by VIN

> Fetch one VIN straight from the dealer's own site, on demand, instead of reading the last import.

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

<Note>
  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`](/api-reference/endpoints/create-prewarm-session) instead of calling
  this endpoint in a loop.
</Note>

## 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](/api-reference/endpoints/create-prewarm-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`                                                                                 |

<Warning>
  `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.
</Warning>

## The `vehicle` object is shaped differently here

<Warning>
  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](/api-reference/endpoints/get-vehicle),
  [Search Vehicles](/api-reference/endpoints/search-vehicles) — the same fields are
  [returned as JSON strings](/concepts/vehicles) 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.
</Warning>

Every other field follows the [vehicle schema](/concepts/vehicles), 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`

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

```json theme={null}
{
  "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"`.

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

```json theme={null}
{
  "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`

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/get-started/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.