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

# Crash Ratings

> Give the federal crash test star ratings of a vehicle make, model and model year.

Give the federal crash test star ratings of a vehicle by make, model and model year: the overall rating, the frontal and side crash ratings for the driver and the passenger, the side pole rating, the rollover rating with the rollover risk, and whether electronic stability control, forward collision warning and lane departure warning are standard or optional. The result also lists every rated variant of the model year, with the identifier the source gives each, so a second call with `variant` can rate another one. Use it to compare the safety of vehicles before a purchase, a fleet decision or an insurance review. Covers US passenger vehicles rated in the federal New Car Assessment Program. `rated` is false when the model year has no rated variant or none matches `variant`; a rating is null when the source says the test was not run. To start from a vehicle identification number, decode it first with Vehicle Identification. Recalls and owner complaints have their own tools.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="model_year" type="integer" required>
  The model year. At least 1990. Model year cannot be later than next year.
</ParamField>

<ParamField body="make" type="string" required>
  The vehicle make, for example Toyota. 2 to 40 characters.
</ParamField>

<ParamField body="model" type="string" required>
  The vehicle model, for example Camry. 1 to 60 characters.
</ParamField>

<ParamField body="variant" type="string">
  Text found in the variant description, matched without regard to case, for example AWD or 4 DR. Without it the first rated variant is used. 1 to 40 characters.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `vehicle_crash_ratings`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US National Highway Traffic Safety Administration`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.variants" type="object[]">
  Every rated variant of the model year, in the order the source lists them.
</ResponseField>

<ResponseField name="data.result.variants[].vehicle_id" type="number">
  The identifier the source gives this rated variant.
</ResponseField>

<ResponseField name="data.result.variants[].description" type="string">
  The variant as the source describes it, for example 2024 Toyota CAMRY 4 DR FWD.
</ResponseField>

<ResponseField name="data.result.rated" type="boolean">
  True when a variant was rated and the fields below describe it.
</ResponseField>

<ResponseField name="data.result.vehicle_id" type="number">
  The identifier of the rated variant. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.description" type="string">
  The rated variant as the source describes it. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.overall_rating" type="integer">
  Overall stars, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.front_crash_rating" type="integer">
  Frontal crash stars, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.front_driver_rating" type="integer">
  Frontal crash stars for the driver, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.front_passenger_rating" type="integer">
  Frontal crash stars for the front passenger, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.side_crash_rating" type="integer">
  Side crash stars, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.side_driver_rating" type="integer">
  Side barrier crash stars for the driver, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.side_passenger_rating" type="integer">
  Side barrier crash stars for the rear passenger, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.side_pole_rating" type="integer">
  Side pole crash stars, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.rollover_rating" type="integer">
  Rollover resistance stars, 1 to 5. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.rollover_risk" type="number">
  The chance of rollover in a single-vehicle crash, as a fraction (0.099 is 9.9 percent). `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.tip_result" type="string">
  The outcome of the dynamic rollover test, for example No Tip. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.electronic_stability_control" type="string">
  Whether electronic stability control is fitted: Standard, Optional or No. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.forward_collision_warning" type="string">
  Whether forward collision warning is fitted: Standard, Optional or No. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.lane_departure_warning" type="string">
  Whether lane departure warning is fitted: Standard, Optional or No. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints_count" type="number">
  How many owner complaints the source attaches to the variant. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.recalls_count" type="number">
  How many recalls the source attaches to the variant. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.investigations_count" type="number">
  How many investigations the source attaches to the variant. `null` when the source gives no value.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/vehicle-crash-ratings \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "model_year": 2024,
      "make": "Toyota",
      "model": "Camry",
      "variant": "FWD"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/vehicle-crash-ratings", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "model_year": 2024,
      "make": "Toyota",
      "model": "Camry",
      "variant": "FWD"
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/vehicle-crash-ratings', {
    model_year: 2024,
    make: 'Toyota',
    model: 'Camry',
    variant: 'FWD'
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "vehicle_crash_ratings",
      "result": {
        "variants": [
          {
            "vehicle_id": 19427,
            "description": "2024 Toyota CAMRY 4 DR AWD"
          },
          {
            "vehicle_id": 19426,
            "description": "2024 Toyota CAMRY 4 DR FWD"
          }
        ],
        "rated": true,
        "vehicle_id": 19426,
        "description": "2024 Toyota CAMRY 4 DR FWD",
        "overall_rating": 5,
        "front_crash_rating": 5,
        "front_driver_rating": 5,
        "front_passenger_rating": 5,
        "side_crash_rating": 5,
        "side_driver_rating": 5,
        "side_passenger_rating": 5,
        "side_pole_rating": 5,
        "rollover_rating": 5,
        "rollover_risk": 0.099,
        "tip_result": "No Tip",
        "electronic_stability_control": "Standard",
        "forward_collision_warning": "Standard",
        "lane_departure_warning": "Standard",
        "complaints_count": 51,
        "recalls_count": 1,
        "investigations_count": 0
      },
      "evidence": {
        "source": "US National Highway Traffic Safety Administration",
        "source_kind": "public",
        "retrieved_at": "2026-10-15T12:00:00.000Z",
        "calls": [
          {
            "retrieved_at": "2026-10-15T12:00:00.000Z"
          },
          {
            "retrieved_at": "2026-10-15T12:00:00.000Z"
          }
        ],
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>See [Pricing](/pricing) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.