Resource fields and measurement coverage
This reference is generated from the canonical English repository document. Navigation and guides follow your selected language.
Read Markdown for agents · Repository source
Use this reference with the query options and subscription example. These resources read captured host data; queries do not scan logs, refresh quotas or collect new evidence. They are available to enabled plugins through ctx.data without a Node backend.
This reference describes the current experimental API contract; backward compatibility is not guaranteed. Fields can be null when their source does not provide a value. Missing measurement evidence must remain unknown rather than being replaced with invented values.
Read availability before values
- Check the result's
availability.notCollectedandscopeUnavailableare not measured zeroes. - Check
aggregateCoverage.kindandpageInfo.hasMore. A page is not a whole-source total; even a complete traversal may have partial source coverage. - Check
freshnessand row-specific timestamps. The envelope clock follows usage collection; quota freshness follows the individual quota row'supdatedAtandstatus. - Check field-level evidence. A numeric counter can be a normalized default; its presence alone does not establish measurement support.
Common usage fields
usage rows, session rows, project rows and history buckets use a common usage projection. Model/tool rows expose the subset supported by their attribution maps. A shared field name does not promise that every resource or producer measures it.
| Field | Meaning |
|---|---|
totalTokens |
Accounting total for the row; do not add component coverage totals to it |
inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens, unclassifiedTokens |
Available component counters; missing fields are null. Reasoning accounting depends on the producer; do not automatically add it to the total or output. |
messageCount |
Available message count, not a universal request count |
timedTokens, timedOutputTokens, timedDurationMs |
Matched cumulative timing counters, where measured. Duration is summed measured request time, not elapsed session or scan time. |
capabilities.tokenComponents, capabilities.throughput |
Host capability evidence: true supported, false not fully supported, null unknown. These flags do not promise complete coverage of all tokens or every child row. |
tokenComponentsAvailable |
Separate producer-supplied component flag when present, otherwise null; not inferred from numeric zeroes |
contextTokens, contextWindow, activeTimeMs |
Available context/activity measurements; null does not mean an empty context or no activity |
cost |
{knownUsd, unpricedTokens, currency, completeness}; currency is USD. completeness is complete, partial or unknown. A known subtotal is not necessarily the full bill. |
For normalized period totals, inspect capabilities before interpreting default component/timing counters. Session or bucket producers may not carry these flags: null means unknown, not permission to assume full measurement. For narrower observed evidence, use the explicitly provided model timing or session/model component records below.
A ratio of cumulative timing counters is a period average, not the live token rate; do not calculate it from unsupported, unknown or zero-duration timing.
Resource catalogue
| Resource | Row data and scope |
|---|---|
usage |
Period totals, common usage fields and window: {key, endsAt, timeZone, calendar}. deviceId: null denotes aggregate scope. |
models |
Model identifier/label, attributed tokens, costs and available components. throughput holds the model's matched timedTokens, timedOutputTokens, timedDurationMs, or null counters when absent. |
tools |
Client identifier/label, attributed usage and models: [{model, totalTokens, knownUsd}]. Client timing is not currently projected: throughput counters are null; model names cannot establish client timing. |
devices |
Opaque device ID, host/display names, OS/runtime/version, collection/receipt timestamps, stale state, tracked clients, client state and WSL summary. |
projects |
Opaque project ID, label, common usage fields, model token totals and client token totals. Check coverage for omitted/incomplete projects. |
sessions |
Opaque session/project/parent relations, client, title where enabled, projectPath, timestamps, session kind, turnEnded, waitingForInput, liveActivity, prompt-cache metadata, common usage fields, models and providers. See model components below. |
history |
Daily/monthly buckets or an all-time summary, with common usage fields. Ungrouped buckets can also provide favorite model, message/activity/streak/peak/intensity values. Grouped rows identify their model or client. No hourly/minute resolution. Device-scoped history queries return scopeUnavailable. |
limits |
Provider identity/label, available account identity, plan/status/update metadata, quota windows, balance/tranches, usage summary and reset credits. Quota labels have host-derived displayLabel. Values/units remain provider-specific; credits do not always mean money. |
subscriptions |
Subscription/top-up ledger, opaque account binding where known, currency/amount/calendar fields, notes, top-ups and host-derived calendar/currency/forecast results. Device scope is unavailable. |
status |
Device collection/source health and host collection/sync/availability summaries where supplied. Host preferences include currency, locale, time zone and feature visibility. This is not an App updater or provider incident feed. |
liveRate |
Host-computed matched-counter speed/burn and live/idle/unavailable state for the selected source or an explicit device. Only today is accepted; see below. |
This table describes row content, not additional query options. For supported filters and sorting, use the query reference. Remote/lifetime session detail is limited to what the host actually captured; native display fallbacks do not manufacture accounting rows.
Session model components
Each sessions row has models: [{model, totalTokens, knownUsd, tokenComponents}]. tokenComponents is null without observed evidence, otherwise:
{"totalTokens":50,"inputTokens":10,"cacheReadTokens":20,"cacheWriteTokens":5,"outputTokens":10}Here the nested totalTokens is observed coverage, not extra usage. If the model row contains 80 tokens, only 50 have this component evidence. The four components sum to 45, leaving 5 unknown within that observed portion; the remaining 30 model tokens are also not classified by this record. Do not scale these counters to fill the model total or distribute a session-wide split by model percentages. Only validated host observations are projected; extra producer fields are not copied.
Subscription derivations
derived supplies status, reason, asOfDate, active, nextRenewalDate, coverageEndDate, daysUntilRenewal, paidToDateMinor, monthlyAmountUsd, monthlyAmountUsdReason, topUpTotalMinor, topUpMonthMinor and forecast. Currency/calendar results use the host's captured context. Minor-unit amounts are not dollar amounts.
The top-up forecast reports its own status and reason, matched accountId, balanceUpdatedAt, currency/balance, daily burn, days remaining and exhaustion date when supported. Unmatched, ambiguous, stale, unavailable and not-applicable results remain explicit; do not substitute a different account or present missing rates as USD.
Live token rate
Use {resource: 'liveRate'} for the selected source: local mode uses the local device, shared modes sum independently active device rates. For a specific device, use its opaque ID from devices as filter.deviceId; an ID outside the current plugin/source scope returns scopeUnavailable. The resource works independently of native footer, Tray and Bubble rate-display settings.
Use subscribe to maintain live tracking. A query only reads the current snapshot; it does not start tracking. Without an active subscription for the same source/device scope, supported timing returns waitingForSample. Subscriptions for the same scope share tracking; the last subscription leaving releases its baseline and expiry timer. Closing the owner or disabling the plugin also releases its subscriptions.
For a mounted chart, start with the complete subscription lifecycle example. Set its query to {resource: 'liveRate'} and adapt show to display the first row's state and speed described below. The example handles the initial snapshot, refetching on invalidation, reset and unsubscribe cleanup. Device-scoped subscriptions invalidate only when their own reading changes; aggregate subscriptions also follow changes in contributing devices.
The usual result envelope contains one row when the source exists. availability: 'available' means the resource can describe its state, not that it necessarily has a rate. Check the row's state before interpreting values:
| Field | Meaning |
|---|---|
state |
live (更新中), idle (閒置, retained last reading), or unavailable (無可用讀數) |
reason |
null for live/idle; otherwise waitingForSample, unsupportedTiming, missingData, stale or expired |
speed |
Estimated generated output tokens per second (tok/s) from matched timed-output/duration deltas |
burn |
Matched timed-token consumption per minute (TPM), not currency spend |
sampledAt |
Unix milliseconds of the accepted observation, not a claim about when an individual token was generated |
expiresAt |
Unix milliseconds of the next sample expiry; expiry can change the rate or move it to idle/unavailable |
sampleRevision |
Accepted-sample revision within the current tracker lifetime. Idle transitions do not create a new observed sample. |
deviceCount |
Number of contributing devices in this reading. An idle retained reading describes its last contribution set, not currently active devices. |
id, deviceId, period |
Opaque row identity, null aggregate or selected opaque device ID, and today |
For unavailable, the numeric rate/timestamp/revision fields are null and deviceCount is zero. A supported measured zero can instead be state: 'live', speed: 0: do not replace it with a missing marker using value || '—'.
The first observed snapshot establishes a baseline; a subsequent positive matched-duration delta can produce a reading. Counter regressions and source/client-selection changes reset tracking. New devices establish their own baselines without clearing other devices' active samples; departed/stale devices are removed from both active and retained aggregate readings. Unsupported/incomplete timing does not become a valid zero. Shared-source output sums active per-device samples rather than dividing fleet token totals by summed busy time; this is not proof that every device or token has timing coverage. A shared source containing only stale devices reports reason: 'stale', distinct from an empty source's missingData.
Subscriptions follow host publications and sample expiry, including expiry without a new publication. Samples become idle after their active lifetime and the retained reading clears later; use the returned state and timestamps instead of hard-coding those deadlines.
Refresh the displayed rate, device count and state after every invalidation, even if sampleRevision is unchanged. In a shared source, one device can expire while another stays active: the aggregate might drop from 90 to 50 tok/s without a new observation. Distinguish these time-driven transitions from newly observed samples in chart history; do not label expiry transitions as new measurements or skip redrawing them. On reset, clear chart history before refetching.
Identity and unsupported data
- Query IDs are opaque and scoped to the plugin, selected source and privacy identity. They support joins within that scope, but have no cross-restart persistence guarantee. Do not save them as permanent pin, label or mapping keys, or try to recover raw IDs from them. No formal durable-identity API is currently provided.
- Limits/subscription account identity does not prove which account produced a session's usage. Sessions do not expose a complete account-usage attribution contract.
- Full transcripts, raw credentials and universal TTFT/per-request timelines are not business-data resources. A total token count or session start/end timestamp cannot reconstruct them.
- Host-specific renderer services and DOM extensions are separate from this portable query contract. Reading internal files or inventing missing observations does not establish API support.