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

# Fuel Economy

> Look up official fuel economy, annual fuel cost, electric range and emissions for a vehicle model year.

Get federal fuel economy ratings and annual fuel expenditure for US light-duty vehicles from model year 1984 on. The model name must be the source's: Camry, Camry AWD LE/SE and Camry Hybrid LE are three separate models. Make and model matching is case-insensitive. The result lists the engine and transmission options in source order. `variant` picks among the options by case-insensitive text, for example 4 cyl, 2.5 L or S8; without it the first option is used. An unknown model or unmatched variant completes with `matched: false` and the available options. City, highway and combined ratings are miles per gallon, or miles per gallon equivalent for electric vehicles. Unavailable or inapplicable values are null. The source refreshes weekly; updated\_on dates the selected record.

## Authentication

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

## Request Body

<ParamField body="model_year" type="integer" required>
  The model year, from 1984 through next calendar year. At least 1984. 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 model as the source names it, for example Camry or Camry Hybrid LE. 1 to 60 characters.
</ParamField>

<ParamField body="variant" type="string">
  Case-insensitive text in the option description, for example 4 cyl, 2.5 L or S8; omitted selects the first option. 1 to 60 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_fuel_economy`
</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 Department of Energy and US Environmental Protection Agency`.
</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">
  The selected vehicle record's modifiedOn calendar date; null when no option was fetched.
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.options" type="object[]">
  Available options in source order.
</ResponseField>

<ResponseField name="data.result.options[].vehicle_id" type="integer">
  The source identifier of this engine and transmission option.
</ResponseField>

<ResponseField name="data.result.options[].description" type="string">
  The option text as the source lists it.
</ResponseField>

<ResponseField name="data.result.matched" type="boolean">
  True when an option was fetched and the fields below describe it.
</ResponseField>

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

<ResponseField name="data.result.year" type="number">
  The model year. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.make" type="string">
  The vehicle make. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.model" type="string">
  The model as the source names it. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.vehicle_class" type="string">
  The federal vehicle class. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.drive" type="string">
  The drive configuration. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.transmission" type="string">
  The transmission. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.cylinders" type="number">
  The engine cylinder count; null when inapplicable.
</ResponseField>

<ResponseField name="data.result.displacement_liters" type="number">
  The engine displacement in liters; null when inapplicable.
</ResponseField>

<ResponseField name="data.result.fuel_type" type="string">
  The primary fuel. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.fuel_type_secondary" type="string">
  The secondary fuel; null when blank.
</ResponseField>

<ResponseField name="data.result.city_mpg" type="number">
  City miles per gallon, or miles per gallon equivalent for an electric vehicle. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.highway_mpg" type="number">
  Highway miles per gallon, or miles per gallon equivalent for an electric vehicle. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.combined_mpg" type="number">
  Combined miles per gallon, or miles per gallon equivalent for an electric vehicle. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.combined_kwh_per_100_miles" type="number">
  Combined electricity use in kWh per 100 miles; null for a non-electric vehicle.
</ResponseField>

<ResponseField name="data.result.electric_range_miles" type="number">
  Electric range in miles; null when the source reports zero.
</ResponseField>

<ResponseField name="data.result.annual_fuel_cost_usd" type="number">
  Estimated annual fuel cost in US dollars. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.five_year_cost_vs_average_usd" type="number">
  US dollars over five years versus the average new vehicle: positive is money saved, negative is money spent. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.co2_grams_per_mile" type="number">
  Tailpipe CO2 emissions in grams per mile. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.fuel_economy_score" type="integer">
  Fuel economy score, 1 to 10; null when unavailable.
</ResponseField>

<ResponseField name="data.result.greenhouse_gas_score" type="integer">
  Greenhouse gas score, 1 to 10; null when unavailable.
</ResponseField>

<ResponseField name="data.result.updated_on" type="string">
  The record modification date, YYYY-MM-DD. `null` when the source gives no value.
</ResponseField>

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

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

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/vehicle-fuel-economy', {
    model_year: 2020,
    make: 'Toyota',
    model: 'Camry',
    variant: '4 cyl'
  });
  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_fuel_economy",
      "result": {
        "options": [
          {
            "vehicle_id": 42011,
            "description": "Auto (S8), 6 cyl, 3.5 L"
          },
          {
            "vehicle_id": 42015,
            "description": "Auto (S8), 4 cyl, 2.5 L"
          }
        ],
        "matched": true,
        "vehicle_id": 42015,
        "year": 2020,
        "make": "Toyota",
        "model": "Camry",
        "vehicle_class": "Midsize Cars",
        "drive": "Front-Wheel Drive",
        "transmission": "Automatic (S8)",
        "cylinders": 4,
        "displacement_liters": 2.5,
        "fuel_type": "Regular Gasoline",
        "fuel_type_secondary": null,
        "city_mpg": 29,
        "highway_mpg": 41,
        "combined_mpg": 34,
        "combined_kwh_per_100_miles": null,
        "electric_range_miles": null,
        "annual_fuel_cost_usd": 1900,
        "five_year_cost_vs_average_usd": 2000,
        "co2_grams_per_mile": 264,
        "fuel_economy_score": 8,
        "greenhouse_gas_score": 8,
        "updated_on": "2019-11-08"
      },
      "evidence": {
        "source": "US Department of Energy and US Environmental Protection Agency",
        "source_kind": "public",
        "retrieved_at": "2026-10-19T12:00:00.000Z",
        "calls": [
          {
            "retrieved_at": "2026-10-19T12:00:00.000Z"
          },
          {
            "retrieved_at": "2026-10-19T12:00:00.000Z"
          }
        ],
        "as_of": "2019-11-08"
      }
    }
  }
  ```
</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.