The Tesla Fleet API vehicle_data JSON does not contain an official battery_health or soh (State of Health) field that could simply be read and shown to the user as "battery health = 92%".
Tesla's BMS (Battery Management System) computes an internal health estimate using proprietary algorithms and an "expected retention" model, but this value is not exposed through the Fleet API.
Any battery health figure we produce is therefore an indirect estimation and must be clearly labelled as such in the report.
The following fields from vehicle_data are relevant for battery health estimation:
| Field | Type | Example | Description |
|---|---|---|---|
charge_state.usable_battery_level |
int | 73 |
Usable SoC (State of Charge) in % |
charge_state.battery_level |
int | 74 |
Total battery level in % (incl. buffer) |
charge_state.battery_range |
float | 243.31 |
EPA rated range in miles at current SoC |
charge_state.ideal_battery_range |
float | 243.31 |
Ideal range in miles at current SoC |
charge_state.est_battery_range |
float | 242.74 |
Estimated range based on recent driving |
charge_state.charge_energy_added |
float | 17.74 |
kWh added in last charge session |
Additionally, Fleet Telemetry (streaming API) may provide:
| Field | Description |
|---|---|
EnergyRemaining |
Nominal energy remaining in the battery (kWh) |
If energy_remaining_kwh (from Fleet Telemetry EnergyRemaining) and usable_battery_level are both available:
full_usable_kwh = energy_remaining_kwh / (usable_battery_level / 100)
Then, given a reference capacity for the model when new:
estimated_soh = (full_usable_kwh / nominal_new_capacity_kwh) * 100
Example:
- energy_remaining_kwh = 57.0 kWh
- usable_battery_level = 73%
- full_usable_kwh = 57.0 / 0.73 = 78.08 kWh
- Model 3 Long Range nominal = 82 kWh (new)
- estimated_soh = 78.08 / 82.0 * 100 = 95.2%
If energy_remaining_kwh is not available, use rated range at 100% SoC:
full_rated_range = battery_range / (usable_battery_level / 100)
Then compare to the EPA rated range when new:
estimated_soh = (full_rated_range / epa_rated_range_new) * 100
Example:
- battery_range = 243.31 miles (at 73% SoC)
- full_rated_range = 243.31 / 0.73 = 333.3 miles
- Model 3 LR EPA range (new) = 358 miles
- estimated_soh = 333.3 / 358 * 100 = 93.1%
The gap between battery_level and usable_battery_level gives a rough sense of the buffer Tesla reserves:
buffer_percent = battery_level - usable_battery_level
A growing buffer may indicate increasing degradation, as Tesla's BMS reserves more capacity to compensate for worn cells. However, this is only a directional indicator, not a precise measurement.
These are nominal usable capacities for new vehicles. The actual capacity varies by production batch.
| Model | Variant | Nominal Capacity (kWh) | EPA Range (miles) |
|---|---|---|---|
| Model 3 | Standard Range Plus (2019-2021) | 50 | 263 |
| Model 3 | Standard Range (2022+, LFP) | 60 | 272 |
| Model 3 | Long Range (2019-2023) | 75-82 | 358 |
| Model 3 | Long Range (2024+, Highland) | 75 | 363 |
| Model 3 | Performance (2019-2023) | 75-82 | 315 |
| Model Y | Long Range | 75-82 | 330 |
| Model Y | Performance | 75-82 | 303 |
| Model S | Long Range (2021+) | 100 | 405 |
| Model S | Plaid | 100 | 396 |
| Model X | Long Range (2021+) | 100 | 348 |
| Model X | Plaid | 100 | 333 |
Identifying the variant can be done from:
- vehicle_config.car_type (e.g., "model3")
- vehicle_config.trim_badging (e.g., "74d" for LR dual motor)
- vehicle_config.efficiency_package (e.g., "M3POPPYSEED2024")
- VIN decoding (position 8 = battery type, position 10 = model year)
- /api/1/dx/vehicles/options endpoint (e.g., $MT352 = Premium LR AWD)
| Factor | Impact | Mitigation |
|---|---|---|
| Temperature | Cold weather temporarily reduces usable capacity | Note ambient temp in report |
| SoC level | Estimates are more accurate near 100% and 0% SoC | Prefer readings at high SoC |
| Recent driving | est_battery_range fluctuates with driving style |
Use battery_range (rated), not est_battery_range |
| Software calibration | Tesla periodically recalibrates BMS, shifting range | Acknowledge in report |
| Battery chemistry | LFP vs NCA have different degradation curves | Use correct reference capacity |
| Phantom drain | Sentry mode and background processes consume energy | Measure with car idle |
| Model year changes | Tesla updates battery specs between production runs | Maintain up-to-date reference table |
~XX% with clear "estimated" labelXX.X kWh (calculated)XX kWh (from reference table)~X.X% from nominalThe report must clearly state:
Estimated Battery Health
This estimate is calculated from Tesla Fleet API telemetry data using the vehicle's current energy level and state of charge. It is an approximation and may differ from Tesla's internal BMS assessment. Factors such as temperature, recent driving patterns, and software calibration can affect the reading.
Has energy_remaining_kwh (Fleet Telemetry)?
YES -> Method 1 (kWh capacity estimation)
NO -> Is usable_battery_level > 20%?
YES -> Method 2 (range-based estimation)
NO -> Show "Insufficient data for reliable estimate"
(low SoC readings are inaccurate)
This document is based on a team Slack discussion (2026-02) analyzing what battery health data is and isn't available from the Tesla Fleet API, and how to produce a meaningful estimate for the Car Pulse Tracker PDF report.
Key takeaway: Tesla's API provides the raw ingredients (usable_battery_level, energy_remaining, rated_range) but not a pre-computed health score. We compute it ourselves and label it honestly as "estimated".