ts usage

Show how busy a server is: how many sessions, users, and applications are active right now, and the totals over a window. Reach for it when you want a number in one line rather than a report to open.

Usage

ts usage [summary] [--since=DATE] [--until=DATE]

Description

summary is the only action and it is the default, so ts usage and ts usage summary do the same thing. Any other word is rejected rather than ignored.

The output has two halves that answer different questions. The first three lines are live counters — sessions, distinct users, and distinct applications active at the moment the server answers. The last line covers the window: how many sessions ran, how many distinct users ran them, and how many distinct applications were involved across that period.

The window defaults to the last seven days ending now. --since and --until move either end; both take ISO-8601 values, and the server rejects a window whose start is after its end. Narrowing the window changes only the window line — the live counters are a snapshot of the present and do not move with it.

This command is deliberately a headline. It has no per-user, per-application, or per-session breakdown; when you need to know who or which application rather than how many, export the detail with ts report or read it in the Administration site.

Options

Flag	Description	Default/Values	Notes
--since	Window start.	ISO-8601; default 7 days ago	E.g. 2026-07-01 or 2026-07-01T09:00:00Z.
--until	Window end.	ISO-8601; default now	Must not be earlier than --since.

Examples

# Right now, and the last week
ts usage

# One calendar month
ts usage --since=2026-07-01 --until=2026-08-01

# The same thing, action spelled out
ts usage summary

# Feed a monitoring check
ts usage --format=json

# There is no breakdown action — this fails
ts usage top-users

Output

Active sessions: 12
Active users:    9
Active apps:     4
Window 2026-07-25T00:00:00.0000000Z to 2026-08-01T00:00:00.0000000Z: 431 sessions, 88 users, 17 apps

--format=json returns the same figures as a realtime object and a window object, which is the form to parse in a script.

Exit Codes

0 on success, including on an idle server where every count is zero. -1 when the action word is not summary, and when the server rejects the window — a --since later than --until is reported as a bad request, while a value the server cannot parse as a date surfaces as a server error rather than a validation message, so check the format first if a window fails unexpectedly. -4 when no account is signed in and -5 when the signed-in account is not a Server Administrator.

Related Commands

• ts report — The per-user and per-session detail behind these totals, as CSV or PDF.
• ts sessions — The individual sessions making up the live counters.
• ts ai usage — Token and AI usage totals, which are counted separately.