Vehicles.dev

Premium report API · asynchronous workflow

Vehicle history reports by VIN

Start with one 17-character VIN. The API creates a durable report owned by your Vehicles.dev account, gives you a stable report ID, and lets you poll until the provider-backed result is ready. A UUID idempotency key makes retries safe when a client loses the first response.

Coverage is record-dependent. A completed report returns the provider data available for that VIN; it is not a promise that every title, accident, odometer, or ownership category exists for every vehicle.

View Pro and Scale plansSee the workflow

Pricing

Starter
Not available
Pro
$1.99per completed report
Scale
$0.99per completed report

Vehicle History Reports are available on Pro and Scale. Starter accounts cannot order reports. Billing settles only after the canonical result is stored. Invalid or unsupported VINs, failed generations, and action_required outcomes cost $0.

Create, poll, retrieve

  1. Create the report once

    Send POST /v1/vehicles/history-reports with the VIN and a UUID Idempotency-Key. The key needs reports:order scope. A 202 response includes Location and Retry-After. If that durable report is later visible with status submitting after an uncertain create response, call POST /v1/vehicles/history-reports/{id}/retry with the same order scope. The server preserves the original provider idempotency key.

  2. Poll at the server’s cadence

    Call GET /v1/vehicles/history-reports/{id} with reports:read. Respect Retry-After while status is queued or processing; do not hammer the provider.

  3. Fetch, view, or print the stored result

    Once status is completed and hasResult is true, call GET /v1/vehicles/history-reports/{id}/result. A result requested too early returns a retryable 409 report_not_ready rather than an empty report. The branded dashboard view presents the same account-owned result for viewing or printing; there is no separate file-artifact endpoint.

Create a report
curl -i https://api.vehicles.dev/v1/vehicles/history-reports \
  -X POST \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"vin":"1FTFW3L57TKD09376"}'
202 · report accepted
HTTP/2 202
location: /v1/vehicles/history-reports/7ae77ee8-94af-4c25-85f1-45a2ab1c6475
retry-after: 3

{
  "id": "7ae77ee8-94af-4c25-85f1-45a2ab1c6475",
  "vin": "1FTFW3L57TKD09376",
  "status": "queued",
  "hasResult": false,
  "retryAfterSeconds": 3,
  "replayed": false,
  "createdAt": "2026-08-16T12:00:00.000Z",
  "updatedAt": "2026-08-16T12:00:00.000Z"
}

What the result can contain

The result endpoint returns one canonical provider object inside report. Its exact keys vary by VIN and provider coverage, but the report viewer recognizes these groups when they are returned:

  • Vehicle & equipment

    Decoded identity, specifications, installed equipment, options, and feature details.

  • Ownership

    Available owner sequence, registration, location, and use records.

  • Title & brands

    Title events and provider-reported brands such as rebuilt or flood.

  • Odometer & mileage

    Reported mileage events and possible odometer inconsistency signals.

  • Damage & accidents

    Reported collision, damage, severity, and event details.

  • Theft

    Available theft records and recovery status.

  • Junk, salvage & insurance

    Junk, salvage, insurance, and total-loss records when available.

  • Safety recalls

    Provider-returned safety recall records.

  • Sales & auction history

    Sale, auction, and listing events, sometimes including price or media.

  • Market analysis

    Available market, valuation, and depreciation context.

A missing group means coverage was unavailable, not that the vehicle is clean. A present but empty group means no records were returned in that category. Integrations should preserve unrecognized provider fields because new fields can appear without notice.

Vehicle history report guides by model

These pages pair the VIN-specific workflow with truthful model-level asking-price context from our committed marketplace snapshot. The aggregate never substitutes for the report.

Frequently asked questions

Does every VIN have the same history coverage?

No. Report coverage depends on the records available for that VIN. A completed result may contain title, accident, odometer, or ownership events when the provider has them, but the integration must inspect the returned report instead of promising that every category exists.

How does the asynchronous API workflow work?

Create the account-owned job with POST /v1/vehicles/history-reports, follow the explicit POST /v1/vehicles/history-reports/{id}/retry path only if the durable job remains in submitting after an uncertain create response, follow the Retry-After header while polling GET /v1/vehicles/history-reports/{id}, then fetch GET /v1/vehicles/history-reports/{id}/result after status becomes completed.

How much does a vehicle history report cost?

Pro is $1.99 per completed report. Scale is $0.99 per completed report. Invalid or unsupported VINs, failed generations, and action-required outcomes cost $0.

How do I prevent duplicate report orders?

Send a UUID Idempotency-Key when creating the report. Repeating the same key and VIN returns the same account-owned report; reusing that key for a different VIN is rejected rather than ordering and charging twice.

Can a Starter account order a vehicle history report?

No. Starter accounts cannot order vehicle history reports. Upgrade to Pro or Scale before creating or retrying a report; existing report results remain account-owned.