Skip to content
Last updated

tdx usage

Show estimated AI Suite usage for the current profile, with monthly history and a breakdown by client.

tdx usage
tdx usage --json
tdx usage --jsonl
tdx --profile production usage

The report covers one authenticated caller: the profile selected with --profile, or otherwise the active session, TDX_PROFILE, or global configuration. With no named profile, tdx uses its default credentials. Default, ordinary named, and Treasure Work profiles all request server usage; the profile's name does not determine which data source is used.

The report leads with the current UTC month and today, followed by Monthly History and Usage by Client, sorted by this month's usage. Totals and request counts are available in JSON rather than the table, because they cover a different window.

Server usage and client breakdown

The LLM Proxy's /v1/work/usage returns the authenticated caller's usage across machines and clients. The summary and client rows come from the same daily buckets, so their credits and costs reconcile. The server's X-TD-Client values appear directly, including tdx/claude, tdx/codex, tdx/opencode, tdx/pi, and separate Treasure Work clients. Requests without a client header appear as (unknown). No local recorder is required for Pi to appear in server results.

Each report makes one request for the latest 31 UTC days, grouped by client. Today and Month are the current UTC day and calendar month; JSON credits and requests cover the last 31 days. Server credits use credit_consumption directly and are not repriced locally. The profile label is for the credentials used to fetch the report; it does not filter the server's client list.

The request uses the selected profile's credentials and saved site. Default credentials are looked up without substituting a named profile called default. Normal API-key, OAuth, and environment credential resolution applies to this one caller; tdx does not query other configured profiles.

Server snapshots are cached for 2 minutes in the global tdx cache's work-usage/ directory, separately for each profile, site, and credential identity. Refreshes have a 5-second timeout, with a 60-second retry delay on failure. If a refresh fails, tdx retains the last good snapshot for both summary and client rows. If no snapshot is available, including when access is denied, it shows the current profile's local figures with a stderr note. Successful refreshes are quiet. There is no need to clear the local ledger or switch profiles to enable server reporting.

The endpoint is currently feature-gated. Server data itself may lag: recent requests normally appear within seconds, while closed hours can take about 30 minutes to settle. Amounts are estimates, not invoices.

Monthly history and local data

Monthly History shows the current month, matching the summary, followed by recorded months within the preceding 11 calendar months. Older months come from the current profile's local recordings on this machine, since the endpoint cannot return complete older months. They can miss other devices and clients. The current month is marked month to date; JSON monthly rows distinguish source: "report" from source: "local".

Local source figures, used only when no server snapshot exists, keep their recorded totals. Known launcher labels are displayed as tdx/claude, tdx/codex, and tdx/opencode without rewriting the ledger. Historical Treasure Work sources are grouped as Treasure Work. These local figures do not include Pi requests, which bypass the local recorder. Last used is also based on local recordings.

Local estimates use each profile's /v1/work/models catalog prices, including long-context and cache rates, with bundled estimates when catalog prices are unavailable. Auto requests use the model that served them when reported, otherwise the first model in the alias chain. Codex records new persisted rollout token events while tdx codex runs; existing session history is not imported. Claude and OpenCode record usage through their integrated proxy.

JSON and cost display

JSON output includes monthly, summary, profiles, and sources. profiles holds the current profile only, and sources holds the server client breakdown (or local sources when server data is unavailable). Profile and source rows include credits, todayCredits, monthCredits, and requests. Monthly rows include month, credits, and source.

For internal employees, identified by cached treasure.ai or treasure-data.com identity, the table shows estimated USD costs instead of credits, using the same conversion as tdx claude statusline. Employee JSON adds todayCostUsd, monthCostUsd, and totalCostUsd to the summary; costUsd, todayCostUsd, and monthCostUsd to profile and client rows; and costUsd to monthly rows. These numeric estimates are unrounded. Other users and profiles without cached employee identity see credits.

tdx usage replaces the removed tdx claude usage and tdx opencode usage commands. The Claude status line remains entirely local and does not call /v1/work/usage.