Cost of Ownership API

What comes back

A flat, EPA-shaped object. annualFuelCostUsd (2350 for a 2021 Camry) and fiveYearFuelCostUsd (11750) are the headline figures, combinedMpg is EPA's combined city/highway number truncated to an integer, co2GramsPerMile is tailpipe grams per mile, and fuelType is EPA's label — "Regular", "Premium" or "Electricity". Two fields do the honest work: config names the exact EPA trim configuration that was priced, for example "Auto (S8), 6 cyl, 3.5 L", and trimsAvailable tells you how many configurations exist for that year/make/model. Your make, model and year come back echoed verbatim and unnormalized. Every numeric field is nullable, because EPA occasionally omits them, and note is a fixed disclaimer present on every response.

curl -sS -G https://api.vehicles.dev/v1/vehicles/ownership-costs \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -d make=Toyota -d model=Camry -d year=2021

{
  "annualFuelCostUsd": 2350,
  "co2GramsPerMile": 338,
  "combinedMpg": 26,
  "config": "Auto (S8), 6 cyl, 3.5 L",
  "fiveYearFuelCostUsd": 11750,
  "fuelType": "Regular",
  "make": "Toyota",
  "model": "Camry",
  "note": "Fuel/operating cost from EPA; excludes maintenance, insurance, and depreciation.",
  "source": "carscrape",
  "trimsAvailable": 1,
  "year": 2021
}

The complete parameter table, the response-field dictionary and the per-endpoint error codes live in the reference: full parameter reference for /v1/vehicles/ownership-costs.

What it is actually built on

Unlike our valuation and depreciation endpoints, this one is not backed by scraped data. Each request makes two live calls to EPA's fueleconomy.gov: one to resolve your year/make/model into the list of trim configurations EPA holds, and a second to fetch the figures for the first configuration in that list. Nothing is cached in between, and the route runs against a 15-second budget. Because EPA performs the lookup, make and model matching is case-insensitive here — a genuine difference from the depreciation endpoint, which is exact and case-sensitive — but your values are echoed back exactly as you sent them rather than normalized. annualFuelCostUsd is EPA's own estimate at 15,000 miles a year against current national average fuel prices, and fiveYearFuelCostUsd is simply that figure multiplied by five.

Data source

Two live calls to EPA fueleconomy.gov per request: one to resolve year/make/model to trim configurations, then one for the first configuration returned. Not scraped data, and not cached.

Route budget

15 s

Billed per

model estimate, successful responses only

MCP tool

get_ownership_costs

Limits: what this endpoint will not do

Fuel only. There is no maintenance schedule, no insurance premium, no tire or tax or registration estimate, and no depreciation — the fixed note string in every response says so, and you should surface an equivalent caveat in your UI. The figures describe EPA's first trim configuration only: when trimsAvailable is greater than 1, treat the numbers as one configuration's, not the model's. For the 2021 Camry, EPA resolves the V6 ("Auto (S8), 6 cyl, 3.5 L"), not the best-selling four-cylinder. The five-year figure is arithmetic, not a forecast: annual × 5, with no inflation, discounting or fuel-price projection. Error behaviour is counterintuitive and worth coding for: EPA coverage starts at 1984, and an unknown model or a pre-1984 year makes EPA return an empty body, which surfaces as a 503 ownership_upstream_error rather than a clean 404. The 404 ownership_not_found only fires in the rarer case where EPA returns a well-formed menu with zero options. So a 503 here is more often bad input than an outage — do not blind-retry it. Latency is upstream-bound by design, since it is two live round trips with no caching. There is also no VIN parameter and no state-level fuel pricing; figures use EPA's national assumptions. Ownership Costs shares the free Starter plan's 1,000 monthly calls. After that shared allowance, successful calls cost $0.045 from the one-time $10 signup credit — about 222 additional calls — and return 402 insufficient_credits only when both are exhausted. The endpoint is available now and successful responses use the published catalog rate. Standard plans include no SLA.

What teams build with it

Integrating it properly

The reference ships the bare curl. This is the shape worth deploying: a typed client that branches on the RFC 9457 code slug rather than the human-readable title, and retries only the codes this endpoint marks retryable.

const API = "https://api.vehicles.dev";

// Only these codes are marked retryable for this endpoint. Everything else is terminal.
const RETRYABLE = new Set(["ownership_upstream_unavailable", "ownership_upstream_error"]);

export async function getOwnershipCosts(params: Record<string, string>, attempt = 0): Promise<GetOwnershipCostsResponse> {
  const response = await fetch(
    `${API}/v1/vehicles/ownership-costs?${new URLSearchParams(params).toString()}`,
    {
      headers: {
        Accept: "application/json",
        Authorization: `Bearer ${process.env.VEHICLES_API_KEY ?? ""}`
      },
      // The route budget is 15 s; allow it plus headroom.
      signal: AbortSignal.timeout(20_000)
    }
  );

  if (response.ok) return (await response.json()) as GetOwnershipCostsResponse;

  // Failures are application/problem+json. Branch on `code`, never on the human-readable title.
  const problem = (await response.json()) as { code: string; detail?: string };
  if (RETRYABLE.has(problem.code) && attempt < 3) {
    await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
    return getOwnershipCosts(params, attempt + 1);
  }
  throw new Error(`${response.status} ${problem.code}: ${problem.detail ?? ""}`);
}

How to check it is behaving

The route enforces a 15-second upstream budget, so a slow dependency returns a problem document instead of holding your request open. Exactly 2 codes are marked retryable here — ownership_upstream_unavailable and ownership_upstream_error — and everything else documented for this endpoint is terminal, so backoff on anything else just burns your rate limit. Billing is success-only: failed calls release their reservation, so you can measure error rates and hold-out accuracy against your own data without paying for the failures. Usage is visible per endpoint in the dashboard.

What this one endpoint costs

Priced per model estimate. The platform fee buys throughput and endpoint access; the unit price covers the data work. Worked at 50,000 successful calls a month so you can see where the plans cross over — the full price matrix is in the reference.

Eligible for the Starter plan's included monthly calls; past those it draws on your credit balance. Data fees are prepaid from credits on every plan: when included calls and credits cannot cover a call you get 402 insufficient_credits rather than an overage bill. Published rates are active and apply only to successful responses. Standard plans include no SLA.

Questions engineers actually ask

Where to go next

Most integrations chain two or three of these. The ones that pair with cost of ownership api most often:

• Car Depreciation APIMSRP retention by model year, a smoothed age 0–12 retention curve and one fitted annual decay rate, for 223 covered make/model pairs.
• Vehicle Valuation APIAn ML-predicted current asking price in whole USD for a year/make/model, with the model's 3.7% median holdout error reported on every response.
• Vehicle Specs APIThe 20-field NHTSA vPIC factory sheet for a VIN — seats, horsepower, displacement, GVWR class, plant country — read live on every request and never cached.

The reference entry for this endpoint — Ownership Costs in the API documentation — carries the parameter constraints, defaults, response fields and the full error table with retryable flags. Agents can reach the same endpoint as the get_ownership_costs tool on the vehicles-dev-mcp MCP server, and the machine-readable contract is published at https://api.vehicles.dev/openapi.json.

Browse the rest of the catalog on the Vehicle data APIs hub.