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

# Create Prewarm Session

> Warm a handful of VINs in the background so the live lookup that follows is instant.

`POST /v1/sessions`

A live lookup costs a round trip to the dealer. When you know which VINs a conversation is
about — a shopper's shortlist, the three cars in a comparison, an appointment's vehicle —
warm them first. The session fetches them in the background and
[`GET /v1/vehicles/vin/{vin}/live`](/api-reference/endpoints/get-vehicle-live) then answers
from the warm store in tens of milliseconds instead of hundreds.

Returns **`202 Accepted`** immediately. The fetches have not finished when you get the
response; poll [`GET /v1/sessions/{session_id}`](/api-reference/endpoints/get-prewarm-session)
or simply start calling `/live` and take whatever is ready.

## Request

| field           | type      | notes                                                                                             |
| --------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `vins`          | string\[] | required. Up to **25** VINs; 10 is the practical default.                                         |
| `dealership_id` | integer   | optional but recommended. Supplying it skips VIN resolution and makes the first warm read faster. |

```bash theme={null}
curl -X POST "https://api.autosnap.com/v1/sessions" \
  -H "X-API-Key: $AUTOSNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dealership_id": 2119, "vins": ["5YM33CS04V9600257"]}'
```

```json theme={null}
{
  "success": true,
  "status": "accepted",
  "session_id": "77a05ade81f344fbbf231ddb00f6ca98",
  "dealership_id": 2119,
  "created_at": "2026-09-24T15:18:12Z",
  "ttl_s": 600,
  "vin_count": 1,
  "status_counts": { "fetching": 1 },
  "vins": [ { "vin": "5YM33CS04V9600257", "status": "fetching" } ]
}
```

## What gets stored, and for how long

`ttl_s` is **600 seconds**. After that the warm records expire and `/live` goes back to
fetching. Sessions are per API key.

<Note>
  **Only `live` and `gone` outcomes are stored.** A fetch that timed out or was blocked is
  *not* written to the warm store, so a prewarmed answer is never a dressed-up failure — if
  warming failed, the later `/live` call simply does the work itself.
</Note>

Fetches are spaced to the same per-host interval a normal live call respects, so warming
25 VINs at one dealer does not hammer them; different dealers are warmed concurrently.

## Cost

Each warmed VIN is one live fetch. A 10-VIN session costs the same as 10 live calls —
prewarming trades latency for nothing else. Warmed VINs are counted separately in
[usage](/api-reference/endpoints/get-usage) so you can see them apart from direct calls.