# How to Configure TeslaMate Polling Intervals: Environment Variable Guide

> Configure TeslaMate polling intervals by overriding default settings with environment variables. Customize API query frequency at runtime for efficient data collection.

- Repository: [TeslaMate/teslamate](https://github.com/teslamate-org/teslamate)
- Tags: how-to-guide
- Published: 2026-06-18

---

**TeslaMate configures polling intervals through environment variables that override default values defined in the Vehicle state machine, allowing runtime customization of how frequently the Tesla API is queried during different vehicle states.**

The `teslamate-org/teslamate` repository implements a sophisticated **state-machine architecture** in [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex) to manage vehicle data synchronization. Rather than using hard-coded timers, the application derives polling cadences from configurable environment variables, enabling operators to balance API usage against data freshness based on their specific deployment needs.

## How Polling Intervals Work in TeslaMate

TeslaMate uses a **GenStateMachine** to handle vehicle state transitions, where each state (asleep, driving, charging, online) maintains its own polling frequency. The system calculates these intervals at runtime using a helper function that checks for environment variable overrides before falling back to safe defaults.

This design prevents excessive API calls during inactive periods while ensuring high-frequency updates during critical states like driving or charging.

## Default Polling Intervals and Environment Variables

The `Vehicle` module defines six distinct polling modes, each mapped to a specific environment variable and default value. The core logic resides in the `interval/2` helper function at lines 55-61 of [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex):

```elixir
@asleep_interval 30

def interval(env_var, default) do
  System.get_env(env_var)
  |> case do
       nil -> default
       interval -> String.to_integer(interval) |> max(default)
     end
end

```

This function ensures that user-defined values never fall below the default minimums, preventing accidental API rate limit violations.

Specific interval getters expose the following configurations:

- **`asleep_interval/0`**: Controlled by `POLLING_ASLEEP_INTERVAL`, defaults to **30** seconds
- **`driving_interval/0`**: Controlled by `POLLING_DRIVING_INTERVAL`, defaults to **2.5** seconds  
- **`default_interval/0`**: Controlled by `POLLING_DEFAULT_INTERVAL`, defaults to **15** seconds
- **`online_interval/0`**: Controlled by `POLLING_ONLINE_INTERVAL`, defaults to **60** seconds
- **`charging_interval/0`**: Controlled by `POLLING_CHARGING_INTERVAL`, defaults to **5** seconds
- **`minimum_interval/0`**: Controlled by `POLLING_MINIMUM_INTERVAL`, defaults to **0** seconds

Complete documentation for these variables appears in [`website/docs/configuration/environment_variables.md`](https://github.com/teslamate-org/teslamate/blob/main/website/docs/configuration/environment_variables.md).

## Scheduling Mechanism in the State Machine

Once calculated, intervals feed into the `schedule_fetch/3` function (lines 70-77), which translates time values into Erlang timer specifications using the `fetch_timeout/2` macro:

```elixir
defp schedule_fetch(_n, _unit, %Data{import?: true}), do: {:state_timeout, 0, :fetch}
defp schedule_fetch(n, unit, _), do: {:state_timeout, fetch_timeout(n, unit), :fetch}

```

The state machine invokes these schedules during state transitions. For example, when transitioning to the asleep state, the code calls `asleep_interval()` and passes the result to `schedule_fetch/2`:

```elixir
{:next_state, {:asleep, asleep_interval()},
 %Data{...},
 [{:reply, from, :ok}, broadcast_summary(), schedule_fetch(@asleep_interval, data)]}

```

This pattern repeats for driving, charging, and online states throughout the module, ensuring each state maintains its distinct polling cadence.

## Practical Configuration Examples

### Docker Compose Override

To increase the driving poll rate to 5 seconds, modify your [`docker-compose.yml`](https://github.com/teslamate-org/teslamate/blob/main/docker-compose.yml):

```yaml
services:
  teslamate:
    image: teslamate/teslamate:latest
    environment:
      - POLLING_DRIVING_INTERVAL=5
      - POLLING_CHARGING_INTERVAL=10

```

### Programmatic Access

Inspect current intervals from within the application:

```elixir

# Returns the effective driving interval in seconds

current_interval = TeslaMate.Vehicles.Vehicle.driving_interval()
IO.puts("Driving poll interval: #{current_interval}s")

```

### Manual State Timeout Trigger

For debugging or forced updates, manually trigger a fetch using the computed timeout:

```elixir
pid = TeslaMate.Vehicles.Vehicle.whereis(car.id)
interval = TeslaMate.Vehicles.Vehicle.online_interval()
send(pid, {:state_timeout, :fetch, interval})

```

## Summary

- TeslaMate uses **environment variables** (e.g., `POLLING_DRIVING_INTERVAL`) to configure polling intervals without requiring code changes or restarts.
- The `interval/2` helper in [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex) enforces minimum values to prevent API abuse.
- Six distinct modes exist: asleep, driving, default, online, charging, and minimum, each with specific defaults optimized for Tesla API rate limits.
- The **GenStateMachine** applies these intervals via `schedule_fetch/3` during state transitions to maintain appropriate data freshness per vehicle state.

## Frequently Asked Questions

### What is the default polling interval when my Tesla is driving?

The default **driving polling interval** is **2.5 seconds**, defined by the `driving_interval/0` function in [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex). You can override this by setting the `POLLING_DRIVING_INTERVAL` environment variable to any integer value in seconds.

### How do I reduce API calls when the vehicle is parked and online?

Set the `POLLING_ONLINE_INTERVAL` environment variable to increase the delay between status checks. The default is 60 seconds, but you can extend this to 300 seconds (5 minutes) or higher to reduce API usage while the vehicle remains stationary but awake.

### What happens if I set a polling interval lower than the default minimum?

The `interval/2` function uses the `max/2` operator to compare your environment variable value against the hard-coded default. If you specify a value lower than the default (e.g., setting `POLLING_ASLEEP_INTERVAL=5` when the default is 30), TeslaMate will use the default value instead, protecting you from accidental API rate limiting.

### Where are the polling intervals documented in the TeslaMate source code?

Default values and environment variable mappings reside in [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex) at lines 55-61. User-facing documentation appears in [`website/docs/configuration/environment_variables.md`](https://github.com/teslamate-org/teslamate/blob/main/website/docs/configuration/environment_variables.md), which provides comprehensive tables explaining each variable's purpose and acceptable values.