Telemetry

What is collected and never collected: Telemetry and privacy. These calls read and change the same switches as cua telemetry; the SDK records its own events.

telemetry_status#

Telemetry state, and exactly what every event carries.

def telemetry_status() -> TelemetryStatus

Returns TelemetryStatus

telemetry_set_enabled#

Turns usage telemetry on or off for this machine ($CUA_HOME/config.toml, the same switch as cua telemetry off and the Spaces app setting). The environment (DO_NOT_TRACK, CUA_TELEMETRY) still wins.

def telemetry_set_enabled(enabled: bool) -> TelemetryStatus

Returns TelemetryStatus · Raises CuaError

telemetry_show_last#

The last limit events queued or sent from this machine, exactly as sent, as JSON ([{status, payload}]).

def telemetry_show_last(limit: int) -> str

Returns String

telemetry_schema_json#

Every event and property that may be sent, as JSON.

def telemetry_schema_json() -> str

Returns String

telemetry_reset_id#

Deletes the anonymous install id and its salt.

def telemetry_reset_id() -> None

Raises CuaError

StreamStatsReport record#

One stream session's aggregate stats (sampled).

TelemetryStatus record#

Telemetry state.

Returned by telemetry_set_enabled, telemetry_status.

telemetry_acknowledge_notice#

Records that the first-run notice was shown in the app's UI (nothing is sent from a machine before that). Apps that show the notice themselves call telemetry_use_app_notice first so the SDK does not print it.

def telemetry_acknowledge_notice() -> None

telemetry_flush#

Sends queued events now, waiting at most timeout_ms; anything left is kept on disk for a later process.

def telemetry_flush(timeout_ms: int) -> None

telemetry_notice_text#

The first-run notice text (an app shows it in its own UI, then calls telemetry_acknowledge_notice).

def telemetry_notice_text() -> str

Returns String

telemetry_record_bench_run#

Records a finished cua-bench run: the taskset (catalog name, else custom), the aggregate success rate (0 to 1, bucketed), the task count (bucketed) and the outcome (ok, error, cancelled).

def telemetry_record_bench_run(taskset: str, success_rate: Optional[float], task_count: int, outcome: str) -> bool

Returns bool

telemetry_record_feature#

Records use of a Spaces app feature (fixed names: space_create_local, teleport_drop, ... see the docs). Returns whether it was queued; unknown names are dropped.

def telemetry_record_feature(feature: str) -> bool

Returns bool

telemetry_record_onboarding_step#

Records an install or onboarding funnel step (fixed names: onboarding_shown, signed_in, first_space_created, ...; first_* steps count once per install). Returns whether it was queued.

def telemetry_record_onboarding_step(step: str, ok: bool) -> bool

Returns bool

telemetry_record_stream_stats#

Records one stream session's aggregate stats (bucketed and sampled).

def telemetry_record_stream_stats(stats: StreamStatsReport) -> bool

Returns bool

telemetry_set_surface#

Names the SDK surface events are attributed to. Bindings call it at import: sdk_python, sdk_typescript, sdk_swift, sdk_kotlin; apps pass their own product (spaces_app). Unknown names are ignored.

def telemetry_set_surface(surface: str, version: str) -> None

telemetry_use_app_notice#

The host app shows the first-run notice itself (no stderr notice).

def telemetry_use_app_notice() -> None