ts ai usage

Show AI usage and token totals, grouped by workspace, provider, and model. Reach for it to answer where the token spend is going and which model is producing errors.

Usage

ts ai usage [--since=DATE] [--until=DATE] [--workspace=ID] [--csv] [--no-trunc]

Description

ts ai usage aggregates the same model calls that ts ai transcripts lists individually. One row per workspace, provider, and model combination: how many calls, how many failed, input and output tokens, and average latency, heaviest token consumers first. It reads only metadata — no prompt or response content is involved — so unlike reading a single transcript, this command is not audited and you can run it as often as you like.

It answers two questions well. The first is cost: input and output tokens per model tell you which workspace is driving the bill, and switching a heavy workspace to a cheaper default model is a decision this table supports. The second is health: a model with a high ERRORS count relative to CALLS usually means a misconfigured endpoint — a wrong key, a model name the provider does not recognise, or a base URL pointing somewhere stale.

The window is unbounded by default. Unlike ts usage, which looks back seven days unless told otherwise, ts ai usage with no --since covers all retained AI history, so totals will keep climbing between runs and two invocations a week apart are not comparable. Always pass an explicit window when you are comparing periods. A date the command cannot parse is ignored rather than rejected, and that side of the window silently becomes unbounded again.

--workspace takes a workspace id as a GUID; a friendly workspace name is rejected by the server rather than resolved. Get the id from ts workspaces.

--format=json returns more than the table shows: the status breakdown split into completed, errors, canceled, and denied, plus cachedInputTokens and the lastUsed timestamp for each row. denied is the one worth watching, and the one the table hides. A denied request was blocked by resolution or route policy before any provider call, so it consumed no tokens, has no latency, and is deliberately excluded from CALLS — the table's CALLS is completed plus errors plus cancellations only. If you are investigating why users say the AI features refuse to work, the denial count is in the JSON and nowhere else in this command.

There is no AI report in ts report, so --csv is the export path for this data. This command is read-only, and stayed that way when the rest of the namespace gained writes: nothing about the AI configuration can be changed from it.

Options

Flag	Description	Default/Values	Notes
--since	Window start.	ISO-8601	Unbounded if omitted — not seven days.
--until	Window end.	ISO-8601	Unbounded if omitted.
--workspace	Return only this workspace's usage.	Workspace id (GUID)	A friendly id is rejected, not resolved.
--csv	Tab-separated output, nothing truncated.		For spreadsheets and pipes.
--no-trunc	Do not truncate columns.

Examples

# Everything retained, all workspaces
ts ai usage

# Last month, for a cost review
ts ai usage --since=2026-07-01 --until=2026-08-01

# One workspace, by id
ts ai usage --workspace=8c1f2a45-6b0d-4e91-a7c2-3d5e9f014b6a

# Export a month's totals
ts ai usage --since=2026-07-01 --until=2026-08-01 --csv > ai-usage-july.tsv

# Denied and canceled calls, which the table folds away
ts ai usage --since=2026-07-01 --format=json

# CALLS does not include policy-denied requests, so a workspace whose calls
# are all being blocked can show a near-empty row here.
ts ai usage --workspace=8c1f2a45-6b0d-4e91-a7c2-3d5e9f014b6a --format=json

# No --since means all retained history, so this total is not "this month"
# and will not match the same command run next week.
ts ai usage

Output

WORKSPACE  PROVIDER   MODEL              CALLS  ERRORS  IN      OUT    AVG MS
Research   Anthropic  claude-sonnet-4-5  418    3       912430  88210  1904
Support    OpenAI     gpt-4o-mini        1204   187     220145  40388  742

An ERRORS count that large next to CALLS points at the endpoint, not at the users — check ts ai endpoints and then a failing call in ts ai transcripts.

Exit Codes

0 on success, including a window with no activity — the command says so rather than printing an empty table. -1 when the server rejects the request, most commonly a --workspace value that is not a GUID. -3 when the server cannot be reached. -4 when no account is signed in or the ticket has expired. -5 when the account is not a Server Administrator.

Related Commands

• ts ai — The rest of the namespace.
• ts ai transcripts — The individual calls behind these totals.
• ts ai endpoints — The providers and default models named in each row.
• ts usage — Session and user usage, which defaults to a seven-day window.
• ts report — The built-in CSV and PDF exports, none of which cover AI.