Relay usage
The Relay usage row in Settings and the notice past the monthly relay allowance.
The Relay usage row in Settings and the notice past the monthly relay allowance.
These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (import CuaSpacesFFI); the Rust tab shows the cua-spaces-ffi crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.
app_relay_usage reads the account's relay allowance this month from the relay (GET /v1/usage, as cua usage does) with the session's Devices and an account token. app_relay_usage_view derives the Settings row (AppRelayUsageView) and, past the allowance, AppRelayAllowanceNotice: one line with Upgrade, dismissed per month and reason. Nothing stops at the limit.
AppRelayAllowanceNotice record#| Field | Type | Default | Description |
|---|---|---|---|
text | String | "You've used your free relay allowance for this month. ..." | |
upgrade | String | UPGRADE. | |
upgrade_url / upgradeUrl | Option<String> | What Upgrade opens; none: no Upgrade button. | |
dismiss | String | DISMISS. | |
dismiss_key / dismissKey | String | What a dismissal remembers: the month and the reasons. A new month, or another limit reached, shows the notice again. |
AppRelayUsage record#Returned by app_relay_usage.
| Field | Type | Default | Description |
|---|---|---|---|
metered | bool | The relay meters this account (false: no allowance applies). | |
period | String | The month counted (2026-10). | |
plan | String | free, pro, team, ... | |
team | Option<AppRelayUsageTeam> | The team whose allowance is pooled. | |
live_sessions / liveSessions | u32 | Live sessions now. | |
live_sessions_limit / liveSessionsLimit | Option<u32> | Live sessions allowed at once (none: no limit). | |
hours_used / hoursUsed | f64 | Relay hours used this month (the team's, when pooled). | |
hours_limit / hoursLimit | Option<f64> | Relay hours allowed this month (none: no limit). | |
my_hours_used / myHoursUsed | f64 | This account's own relay hours this month. | |
soft_limit_reached / softLimitReached | bool | Past the allowance (sessions keep working). | |
reasons | Vec<String> | What is past it: sessions and/or hours. | |
upgrade_url / upgradeUrl | Option<String> | Where to get more (https only; see checked). |
AppRelayUsageTeam record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | Team id. | |
seats | u32 | Seats sharing the allowance. |
AppRelayUsageView record#Returned by app_relay_usage_view.
| Field | Type | Default | Description |
|---|---|---|---|
label | String | ROW_LABEL. | |
line | String | "Live sessions 1 of 2 · Relay hours 6.5 of 20 this month", then the team pool when there is one. | |
plan | String | "Free plan" (empty when the relay names none). | |
notice | Option<AppRelayAllowanceNotice> | Past the allowance. |
app_relay_usage#The account's relay allowance this month (GET /v1/usage on the relay
devices uses, as cua usage reads it) with account_token; none
from a relay that meters nothing. Both Spaces apps read it here.
func appRelayUsage(devices: Devices, accountToken: String) async throws -> AppRelayUsage?| Parameter | Type | Default |
|---|---|---|
devices | Devices | required |
account_token | String | required |
Returns Option<AppRelayUsage> · Async · Raises CuaError
app_relay_usage_view#Settings' "Relay usage" row and the notice past the allowance; none when the relay meters nothing.
func appRelayUsageView(usage: AppRelayUsage) -> AppRelayUsageView?| Parameter | Type | Default |
|---|---|---|
usage | AppRelayUsage | required |
Returns Option<AppRelayUsageView>