UnifiApi.Network.ClientsHistory (UnifiApi v0.4.0)

UniFi Network API (v2) — client history.

Returns past client connections — devices that have been seen on the network even if they're currently offline. Complements UnifiApi.Network.ClientsLive (currently-connected) with longer-tail history.

Requires cookie + CSRF authentication. See UnifiApi.Auth.Cookie.

Client fields

id, mac, name, hostname, oui
is_wired, is_guest
first_seen, last_seen, connected_time
network, ap_mac / ap_name for wireless
manufacturer, os_name

Summary

Functions

list(client, site_id, opts \\ [])

Lists historical clients.

stream(client, site_id, opts \\ [])

Returns a lazy stream that auto-paginates client history via pageSize / pageNumber.

Functions

list(client, site_id, opts \\ [])

@spec list(Req.Request.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Lists historical clients.

Options

:within_hours — withinHours=N.
:type — filter by "WIRED" / "WIRELESS" / "GUEST" / "VPN" (sent as type=...).
:search — string match against name/hostname (searchString=...).
:limit — pageSize=N. Default 200 (reduced from 500 in v0.4.0 to bound per-page memory).
:offset — pageNumber=N.
:raw — when true, return the raw response body binary (skips JSON decoding and v1 envelope unwrap).

stream(client, site_id, opts \\ [])

@spec stream(Req.Request.t(), String.t(), keyword()) :: Enumerable.t()

Returns a lazy stream that auto-paginates client history via pageSize / pageNumber.

Error contract

A mid-stream error does not raise by default: the stream halts and yields {:error, %UnifiApi.StreamError{}, last_page} as its final element, so the enumerable is heterogeneous and Enum.map(stream, & &1["key"]) crashes on a transient 500. Match the tail:

items = Enum.to_list(stream)

case List.last(items) do
  {:error, error, cursor} -> {:error, error, cursor}
  _ -> {:ok, items}
end

Pass raise_errors: true to raise UnifiApi.StreamError instead.

Options

:within_hours, :type, :search — same as list/3; sent on every page request.
:limit — page size (default 200), sent as pageSize.
:max_pages — halt after this many successful pages (default: unbounded).
:max_items — halt once this many clients have been yielded; the final page is truncated to fit (default: unbounded).
:raise_errors — when true, raise UnifiApi.StreamError on a mid-stream error instead of yielding {:error, reason, last_page} as the final element (default: false).

:max_pages, :max_items and :raise_errors are forwarded verbatim to UnifiApi.Client.stream_paged/2 and behave exactly as they do in UnifiApi.Client.stream/3. Any other key raises ArgumentError.

Examples

# The first 100 wireless clients seen in the last week
UnifiApi.Network.ClientsHistory.stream(authed, "default",
  within_hours: 168, type: "WIRELESS", max_items: 100)
|> Enum.to_list()