Repository navigation
Caching and Rate Limits
EeroClient caches reads in memory to stay well under the Eero Cloud API's rate ceiling — here's exactly how it works.
-
In-memory, per-instance — the cache is a plain
dicton theEeroClientinstance (self._cache). It is created fresh in__init__and lives only as long as the client object. - Does NOT persist across processes. Restarting your script, CLI invocation, or worker starts with an empty cache.
-
Not shared between
EeroClientinstances. Two clients in the same process (or two processes) each keep their own cache; writes made through one are not visible to the other's cache until it re-fetches. -
TTL in seconds, default 60, set via the
cache_timeoutconstructor argument:
from eero import EeroClient
client = EeroClient(cache_timeout=120) # cache entries valid for 120 secondsNote:
cache_timeoutonly affects the SDK's own in-memory cache. It has no relationship to server-side caching. TheCACHE_TIMEOUTconstant insrc/eero/const.pyis unused — it's never imported anywhere insrc/. The real default (60) is hardcoded directly onEeroClient.__init__(cache_timeout: int = 60).
Only these EeroClient read methods check and populate the cache. Every other get_* method on EeroClient hits the API on every call:
| Method | Cache key |
|---|---|
get_account() |
"account" |
get_networks() |
"networks" |
get_network(network_id) |
"network" keyed by network_id
|
get_eeros(network_id) |
"eeros" keyed by f"{network_id}_eeros"
|
get_devices(network_id) |
"devices" keyed by f"{network_id}_devices"
|
get_device(device_id, network_id) |
"devices" keyed by f"{network_id}_{device_id}", with the id canonicalised (see Device cache keys) |
get_profiles(network_id) |
"profiles" keyed by f"{network_id}_profiles"
|
get_profile(profile_id, network_id) |
"profiles" keyed by f"{network_id}_{profile_id}"
|
⚠️ Warning:get_eero(eero_id, network_id, refresh_cache=False)accepts arefresh_cachekwarg in its signature, but its implementation never checks or populates the cache — every call goes straight to the API. The kwarg currently has no effect. Every other method not in the table above (get_diagnostics,get_security_settings,get_dns_settings,get_sqm_settings,get_led_status,get_nightlight,get_backup_internet,get_blacklist,get_reservations,get_forwards,get_transfer_stats,get_data_usage,get_speed_tests,get_schedules, and every read in the families added in v8.0.0 — entitlements, events, permissions, notifications, DNS policies, members, WPA3, power saving, backup access points, subnets, WAN) is likewise never cached — it always makes a fresh request.
Note:
get_devices(thread=...)/get_devices(proxied_node=...)bypass the cache in both directions — a filtered list is neither served from nor written to thedevicesentry, because the cached list is the unfiltered one.
Beyond serving repeat reads, three cached entries are reused as the parent= envelope for
domain calls (see Network Targeting):
a fresh network entry is passed to the network-scoped calls whose domain method resolves a
published network link (network reads, the settings-class writes, guest network, speed test,
diagnostics, updates, notifications, DNS writes and DNS policies, members, events, permissions,
WPA3, power saving, subnets/multi-static-IP reads, blacklist, the eero/device/profile lists,
the network-wide device and profile insights, reservations/forwards list+create); calls that
address a child resource (a device, profile, schedule, invite, reservation or forward by id)
or a literal sub-path (DNS read, data usage, the network/per-device/per-profile insights,
entitlements, Thread writes, backup, subnet/WAN writes) run without it. A fresh eeros list
supplies the matching eero's envelope to the eero calls, and a fresh single-device entry is
passed to update_device_via_link. This is read-only — the cached envelope is forwarded as-is and never
merged into a response. When the entry is stale or absent the call simply falls back to the
template URL; nothing is fetched to populate parent=.
A device entry is keyed by the device's last path segment, so a bare id, an API path and an
absolute URL share an entry. When that segment is a MAC address in any common spelling — twelve
hex digits with :, - or . separators or none, in either case — it is reduced to lowercase hex
without separators. Any other id is kept as written. aabbccddeeff, AA:BB:CC:DD:EE:FF and
/2.2/networks/<network-id>/devices/aabbccddeeff therefore name one entry: a read under one
spelling is a hit for the others, and a write under any spelling drops the entry read under
another. Only the cache key is canonicalised; requests still carry the value you passed.
Checking an entry whose TTL has elapsed deletes it (a keyed entry) or resets it to empty (the
single-entry account and networks sections), so a long-lived client does not accumulate stale
copies of devices or profiles it no longer reads. Entries that are never read again stay in memory
until clear_cache() or a write removes them.
The eight cached methods listed above accept a refresh_cache: bool = False keyword argument. Passing refresh_cache=True skips the cache lookup entirely, forces a live API call, and overwrites the cached entry with the fresh response:
# Uses the cache if it's still within cache_timeout
networks = await client.get_networks()
# Bypasses the cache and re-fetches from the API
networks = await client.get_networks(refresh_cache=True)Wipes every cache entry immediately, regardless of TTL:
client.clear_cache()The SDK also calls clear_cache() for you automatically after verify(), logout(), set_session_token(), and clear_session_token() — any operation that changes which session/account you're authenticated as.
The same five operations, plus login(), also forget a preferred network that auto-discovery chose,
so a call without network_id discovers the network of the new credentials instead of reusing the
previous account's. A network chosen with set_preferred_network() is kept. See
Network Targeting.
Write methods invalidate the specific cache entries they affect via internal helpers (_invalidate_network_cache, _invalidate_eeros_cache, _invalidate_device_cache, _invalidate_profile_cache, _invalidate_profiles_list_cache, _invalidate_all_profile_caches, _invalidate_account_cache). Confirmed from src/eero/client.py at v8.0.0:
| Write method | Invalidates |
|---|---|
set_device_nickname, block_device, unblock_device, pause_device, set_device_type, set_device_labels, set_device_secondary_wan_access
|
that device's cache entry (under any spelling of its id) + the network's device list |
update_device_via_link |
that device's cache entry + the network's device list; when profile= is given, also every cached profile of the network and the profile list (the previous profile is unknown, so all are dropped) |
pause_profile, set_profile_blocked_applications
|
that profile's cache entry + the network's profile list |
set_profile_devices |
that profile's cache entry + the network's profile list, and the cache entry of every device named in device_urls + the network's device list. Devices that the call removes from the profile are not named, so their entries are only dropped when they are named elsewhere or expire; call get_device(..., refresh_cache=True) for those. |
create_profile, allow_domain_for_profiles, allow_cnames_for_profiles, block_domain_for_profiles
|
the network's profile list |
rename_profile, delete_profile
|
that profile's cache entry + the network's profile list |
reboot_eero, set_location, set_led, set_led_brightness, set_nightlight, node_action, port_action, nightlight_override
|
the network's eeros list |
set_network_name, set_network_password, clear_network_password, set_hide_5g, set_preferred_update_hour, set_guest_network, set_guest_password, clear_guest_password, run_speed_test, set_thread_enabled, update_thread, regenerate_thread_credentials, set_data_usage_report_settings, apply_update, set_backup_internet, the DNS writes, set_sqm, set_wpa3, set_band_steering, set_upnp, set_ipv6, configure_security, set_notification_settings, allow_domain, allow_cnames, block_domain, set_dhcp, set_connection_mode, set_nat_port_randomization, set_wpa3_per_band, set_mlo_mode, set_fast_transition, set_passpoint_enabled, set_proxied_nodes, set_power_saving, enable_ddns, disable_ddns, set_subnets_config, delete_subnet, set_multistaticip, set_secondary_wan_config
|
that network's cache entry |
Invalidating the network entry also means the next network-scoped call runs without a cached
parent= envelope (template URL) until get_network() repopulates it.
Every invalidation — each _invalidate_* helper above, and clear_cache() — also advances a
client-wide epoch counter, and each cached read captures the epoch before it sends its request.
If the epoch has moved by the time the response arrives, the read was overtaken by a write (or a
session change): its caller still receives the response, but the response is not stored, so it
cannot put a pre-write snapshot back in the cache. The next read fetches fresh. The counter is
client-wide, so a write to one resource also stops every other read then in flight from
populating the cache — at worst one extra request for the next caller.
⚠️ Gotcha: Not every write invalidates a related read. Confirmed not invalidated by this SDK version, despite mutating server-side state that a cached read reflects:
create_schedule,update_schedule,delete_schedule,clear_profile_schedule,enable_bedtime— do not invalidate the profile cache (the profile envelope is whatget_profilecaches; the schedules themselves are never cached)set_nightlight_brightness/set_nightlight_schedule— these delegate toset_nightlight, so they do invalidate the eeros list; listed here only because their names are not in the tableset_account_email,set_account_phone,set_push_settings— do not invalidate theaccountentry (the first two only start a change; the matchingverify_*call does invalidate it).set_account_name,verify_account_email,verify_account_phoneandset_account_consentsdo reset theaccountentry, and also stop aget_account()already in flight from repopulating it.mark_notifications_read, the invite/member writes, the power-saving schedule writes, the backup-access-point writes,set_subnet_content_filters,set_pppoe,led_cycle— nothing is invalidated; none of the reads they affect are cached anywayWorkaround: after any write whose effect you need to see immediately, call the corresponding getter with
refresh_cache=True(or, for uncached reads, simply call it — it is always fresh) rather than trusting the cache to have been cleared for you:await client.set_push_settings({"<setting>": True}) account = await client.get_account(refresh_cache=True)
Every write in the families added in v8.0.0 — and the re-pointed writes listed in
Migration — is unverified against a
live network: the request follows the field names, encoding, and path the API declares for the
operation, but the SDK has not confirmed on a real network that the write persists or what else
it does. Each of these logs one line at WARNING on the module's secure logger immediately
before the request is sent:
Issuing write (<operation>): its side effects have not been fully characterised against a live
network. Read the current state first and skip the write when it already matches -- never retry
a failed write in a loop.
Settings-class writes may reboot the entire mesh. The DNS write on networks/{id}/settings
is confirmed to restart every eero and drop every client; the SDK treats every other write to
that link and its settings-class siblings as capable of the same until proven otherwise —
set_sqm, set_dhcp, set_connection_mode, set_nat_port_randomization, set_mlo_mode,
set_wpa3_per_band, set_fast_transition, set_power_saving, set_subnets_config,
delete_subnet, set_multistaticip, set_secondary_wan_config,
set_device_secondary_wan_access, plus the security toggles (set_wpa3, set_band_steering,
set_upnp, set_ipv6, configure_security) that write the same settings link.
apply_update reboots every node by design, and node_action("POWER_CYCLE_ALL_PORTS_AND_REBOOT")
reboots that eero. The full statement of the discipline this implies, with a worked example, is
in Python API — Writes and safety; the short version is read,
compare, skip if unchanged, never retry in a loop, and treat a 200 as "accepted", not
"settled".
The Eero Cloud API tolerates roughly 100 requests/minute. Exceeding it returns HTTP 429, which the SDK raises as EeroRateLimitException (see Error Handling).
Practical guidance:
- Lean on the cache — the default 60-second TTL alone eliminates most redundant reads in interactive use.
-
Raise
cache_timeoutfor polling workloads — a monitoring loop checking network health every few minutes doesn't need fresh data every call. -
Batch reads — call
get_networks()/get_devices()once and slice the response in memory rather than issuing one request per item. -
Add backoff — see the retry pattern in Error Handling for
EeroRateLimitException. The exception carries the server'sRetry-Afterhint asretry_after(seconds, orNone) so you can honour it — see HonouringRetry-After. The SDK never retries a429itself, and never retries a write for any reason; the only built-in retry is the opt-inget_retriesconstructor option forGETs that fail with a transport error or a5xx(see Configuration).
import asyncio
from eero import EeroClient, EeroRateLimitException
async def main():
async with EeroClient(cache_timeout=300) as client:
while True:
try:
response = await client.get_eeros()
eeros = response.get("data", [])
for eero in eeros:
print(f"{eero.get('location')}: {eero.get('status')}")
except EeroRateLimitException:
await asyncio.sleep(60)
continue
await asyncio.sleep(300) # poll every 5 minutes, matching cache_timeout
asyncio.run(main())The SDK sends a mobile-style User-Agent header on every request, defined in src/eero/const.py:
DEFAULT_USER_AGENT: Final[str] = "eero/3.0 (iPhone; iOS 17.0)"This exists because the Eero Cloud API rate-limits non-mobile clients more aggressively — presenting as the official mobile app reduces the chance of being throttled. It is not configurable. The full per-request header set (Accept, User-Agent, X-Accept-Language, and a per-request Content-Type) is described in Configuration.
MAX_RESPONSE_BYTES (10 MiB, src/eero/const.py) caps how much of a response body the SDK will buffer into memory. Streamed responses exceeding this are aborted mid-read and raised as EeroAPIException — a guard against unbounded memory consumption from a hostile or misbehaving upstream, not a rate-limit mechanism.
The default request timeout is set in BaseAPI._request() and is not configurable via EeroClient's constructor; only the data-usage reads accept a per-call timeout. See Configuration for the exact values and how they interact with EeroTimeoutException.
| Workload | Suggested cache_timeout
|
|---|---|
| Interactive CLI / one-off script |
60 (default) — fine as-is |
| Dashboard with a manual refresh button |
30–60
|
| Background monitoring / polling loop |
180–300
|
| Bulk reporting across many networks |
300+, paired with refresh_cache=True only where freshness matters |
| Anything issuing writes immediately followed by reads | Use refresh_cache=True on the read — don't rely on cache invalidation for the gaps noted above |
| Anything issuing settings-class writes | Read, compare, and skip — the write itself is the expensive event (a possible mesh reboot), not the request |
-
Error Handling —
EeroRateLimitException,EeroTimeoutException, and retry patterns - Configuration — client setup, options, and request timeouts
-
Raw Response Format — the
{"meta": ..., "data": ...}envelope returned by every cached and uncached method alike -
Network Targeting — how
network_idresolution interacts with cache keys, and how cached envelopes becomeparent= - Python API — the read-compare-skip discipline for every write
- Troubleshooting — common issues & fixes
eero-api — unofficial async Python client for the Eero cloud API. Not affiliated with or endorsed by Eero.
This wiki is generated from wiki/ in the main repository — edit there, not here. · MIT License