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

# Vehicle Complaints

> Summarize the safety complaints owners filed for a vehicle make, model and model year, with the newest ones.

Summarize what owners have reported to the US safety regulator about a vehicle by make, model and model year: how many complaints there are, how many involved a crash, a fire, injuries or deaths, which components are reported most, and the newest complaints with their dates, components and the owner's own words. Use it to check a used vehicle before a purchase, a loan, a claim or a fleet decision. Covers vehicles sold in the United States. Complaints are reports by owners, not findings by the regulator. A complaint does not show that the vehicle has a defect, and a model with few complaints is not proven free of one. To see the safety recalls instead, use Vehicle Recalls. `total` is 0 when the model has no complaints.

## Authentication

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

## Request Body

<ParamField body="make" type="string" required>
  The vehicle make, for example Honda. 2 to 40 characters. Letters, digits, spaces and hyphens only.
</ParamField>

<ParamField body="model" type="string" required>
  The vehicle model, for example CR-V. 1 to 60 characters. Letters, digits, spaces, periods and hyphens only.
</ParamField>

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

<ParamField body="limit" type="integer">
  The most complaints to return, newest first. Default 10. From 1 to 25. Defaults to `10`.
</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_complaints`
</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.make" type="string">
  Make.
</ResponseField>

<ResponseField name="data.result.model" type="string">
  Model.
</ResponseField>

<ResponseField name="data.result.model_year" type="number">
  Model year.
</ResponseField>

<ResponseField name="data.result.total" type="number">
  How many complaints were filed for the model, including any beyond `limit`.
</ResponseField>

<ResponseField name="data.result.crashes" type="number">
  How many of all the complaints say a crash was involved.
</ResponseField>

<ResponseField name="data.result.fires" type="number">
  How many of all the complaints say a fire was involved.
</ResponseField>

<ResponseField name="data.result.injuries" type="number">
  The injuries reported across all the complaints.
</ResponseField>

<ResponseField name="data.result.deaths" type="number">
  The deaths reported across all the complaints.
</ResponseField>

<ResponseField name="data.result.components" type="object[]">
  The five components named most often, across all the complaints.
</ResponseField>

<ResponseField name="data.result.components[].component" type="string">
  The vehicle component named in the complaints.
</ResponseField>

<ResponseField name="data.result.components[].complaints" type="number">
  How many of all the complaints name it.
</ResponseField>

<ResponseField name="data.result.complaints" type="object[]">
  The newest complaints, up to `limit`.
</ResponseField>

<ResponseField name="data.result.complaints[].id" type="number">
  The agency complaint number. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].filed_on" type="string">
  The date the complaint was filed, YYYY-MM-DD. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].incident_on" type="string">
  The date of the incident the owner describes, YYYY-MM-DD. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].components" type="string[]">
  The components the owner names.
</ResponseField>

<ResponseField name="data.result.complaints[].crash" type="boolean">
  True when the owner reports a crash.
</ResponseField>

<ResponseField name="data.result.complaints[].fire" type="boolean">
  True when the owner reports a fire.
</ResponseField>

<ResponseField name="data.result.complaints[].injuries" type="number">
  Injuries.
</ResponseField>

<ResponseField name="data.result.complaints[].deaths" type="number">
  Deaths.
</ResponseField>

<ResponseField name="data.result.complaints[].summary" type="string">
  The owner's account, cut to 500 characters. `null` when the source gives no value.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/vehicle-complaints \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "make": "Fiat",
      "model": "124 Spider",
      "model_year": 2019,
      "limit": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/vehicle-complaints", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "make": "Fiat",
      "model": "124 Spider",
      "model_year": 2019,
      "limit": 1
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/vehicle-complaints', {
    make: 'Fiat',
    model: '124 Spider',
    model_year: 2019,
    limit: 1
  });
  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_complaints",
      "result": {
        "make": "Fiat",
        "model": "124 Spider",
        "model_year": 2019,
        "total": 9,
        "crashes": 0,
        "fires": 0,
        "injuries": 0,
        "deaths": 0,
        "components": [
          {
            "component": "SEAT BELTS",
            "complaints": 3
          },
          {
            "component": "FUEL/PROPULSION SYSTEM",
            "complaints": 2
          },
          {
            "component": "ENGINE",
            "complaints": 1
          },
          {
            "component": "FUEL SYSTEM, GASOLINE",
            "complaints": 1
          },
          {
            "component": "UNKNOWN OR OTHER",
            "complaints": 1
          }
        ],
        "complaints": [
          {
            "id": 11578356,
            "filed_on": "2024-03-19",
            "incident_on": "2024-03-19",
            "components": [
              "SEAT BELTS"
            ],
            "crash": false,
            "fire": false,
            "injuries": 0,
            "deaths": 0,
            "summary": "The seat belts do not retract properly, causing a loose seat belt. The vehicle has 10,000 miles on it. This is a common problem with all 2017 to 2020 Fiat Spiders. Replacement seat belt retractors have the same problem."
          }
        ]
      },
      "evidence": {
        "source": "US National Highway Traffic Safety Administration",
        "source_kind": "public",
        "retrieved_at": "2026-01-15T12:00:00.000Z",
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.005 per lookup. See [Pricing](/pricing) for every tool.</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.