Add usage and billing metrics docs page - #1720
Merged
Merged
Conversation
Document how SDK integrators read token counts, context-window utilization, AI credit cost, and account quota via session events and RPC methods (assistant.usage, session.usage_info, session.metadata.contextInfo, session.usage.getMetrics, models.list, account.getQuota). Examples are provided for TypeScript, Python, Go, .NET, Java, and Rust, and the compiled snippets pass the docs-validation harness. Adds a link to the features index. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new feature guide documenting how Copilot SDK integrators can read usage and billing-related signals (per-call tokens, context-window utilization/breakdowns, accumulated session metrics, model pricing, and account quota) across all supported languages, and links it from the features index.
Changes:
- Added
docs/features/usage-and-billing.mdwith multi-language examples for session events and RPC surfaces related to usage/billing. - Linked the new guide from
docs/features/README.mdso it appears in the Features list.
Show a summary per file
| File | Description |
|---|---|
| docs/features/usage-and-billing.md | New feature guide covering usage/billing signals with TypeScript/Python/Go/.NET/Java/Rust examples. |
| docs/features/README.md | Adds the “Usage and Billing” entry to the features index table. |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 5
Comment on lines
+140
to
+147
| in, out := int64(0), int64(0) | ||
| if d.InputTokens != nil { | ||
| in = *d.InputTokens | ||
| } | ||
| if d.OutputTokens != nil { | ||
| out = *d.OutputTokens | ||
| } | ||
| fmt.Printf("%s: in=%d out=%d\n", d.Model, in, out) |
Contributor
There was a problem hiding this comment.
Fixed in 689c887 — added the cost field (with nil/Option guard) to match the other language examples and the documented field table.
Comment on lines
+160
to
+167
| in, out := int64(0), int64(0) | ||
| if d.InputTokens != nil { | ||
| in = *d.InputTokens | ||
| } | ||
| if d.OutputTokens != nil { | ||
| out = *d.OutputTokens | ||
| } | ||
| fmt.Printf("%s: in=%d out=%d\n", d.Model, in, out) |
Contributor
There was a problem hiding this comment.
Fixed in 689c887 — added the cost field (with nil/Option guard) to match the other language examples and the documented field table.
Comment on lines
+208
to
+213
| session.on(AssistantUsageEvent.class, event -> { | ||
| var data = event.getData(); | ||
| long in = data.inputTokens() != null ? data.inputTokens() : 0; | ||
| long out = data.outputTokens() != null ? data.outputTokens() : 0; | ||
| System.out.printf("%s: in=%d out=%d%n", data.model(), in, out); | ||
| }); |
Contributor
There was a problem hiding this comment.
Fixed in 689c887 — added the cost field (with nil/Option guard) to match the other language examples and the documented field table.
|
|
||
| ### On-demand breakdown with `session.metadata.contextInfo` | ||
|
|
||
| Events only fire when the context changes. To read the current breakdown at any moment—for example, right after resuming a session—call `session.metadata.contextInfo`. Pass `0` for the token limits to use the model's defaults. |
Contributor
There was a problem hiding this comment.
Fixed in 689c887 — corrected the description to distinguish the two parameters: 'Pass 0 for promptTokenLimit to use the runtime default; pass 0 for outputTokenLimit if the value is unknown.' This matches the JSDoc on the generated MetadataContextInfoRequest type.
…y contextInfo token limit semantics - Add cost field (with nil/Option guard) to Go, Java, and Rust assistant.usage snippets so all six languages match the documented field table and the 'functionally equivalent' claim in the intro - Correct the description of session.metadata.contextInfo parameters: promptTokenLimit passes 0 to use the runtime default, while outputTokenLimit passes 0 when the value is unknown (per generated types) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
SteveSandersonMS
approved these changes
Jul 31, 2026
SteveSandersonMS
left a comment
SteveSandersonMS
left a comment
Contributor
There was a problem hiding this comment.
Thanks @andyfeller!
Contributor
There was a problem hiding this comment.
Review details
Suppressed comments (2)
docs/features/usage-and-billing.md:27
- The
assistant.usagecostfield is also experimental (and accessing it in .NET raisesGHCP001), but this warning names only the experimental RPCs while the examples usecostas if it were stable. Include the field here so readers get the correct compatibility and diagnostic guidance.
> `session.usage.getMetrics`, `session.metadata.contextInfo`, and `session.metadata.recomputeContextTokens` are marked experimental in the generated RPC surface. In .NET they raise the `GHCP001` experimental diagnostic, which you suppress with `#pragma warning disable GHCP001` or a project-level `<NoWarn>GHCP001</NoWarn>`. Pin both the SDK and the Copilot CLI runtime if your application depends on them.
docs/features/usage-and-billing.md:1153
- This is not currently possible in every documented SDK: Java's generated
ServerAccountApiexposes onlygetQuota()and has no token/request overload. Qualify the guidance so Java users do not search for a nonexistent API or accidentally assume this lookup is scoped per user.
> To read quota for a specific user rather than the connection's global auth context (for example, in a multi-tenant backend), pass that user's GitHub token to `getQuota`. See [Multi-tenancy](../setup/multi-tenancy.md).
- Files reviewed: 2/2 changed files
- Comments generated: 0 new
- Review effort level: Balanced
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new feature guide,
docs/features/usage-and-billing.md, showing how Copilot SDK integrators read usage and billing signals from their applications, and links it from the features index.The page covers the full set of usage/billing surfaces:
assistant.usageeventsession.usage_infoeventsession.metadata.contextInfosession.usage.getMetricsmodels.listaccount.getQuotaDetails
docs-validationharness; Java blocks usedocs-validate: skipand Rust is shown illustratively, consistent with existing docs.session.usage.getMetrics,session.metadata.contextInfo) are flagged as experimental, including the .NETGHCP001diagnostic suppression.totalNanoAiufield and premium-request accounting) are attributed to GitHub Copilot billing documentation rather than asserted by the SDK.Testing
npm run extractthenvalidate:ts,validate:py,validate:go,validate:csfromscripts/docs-validation/— all passing (TypeScript 183/183, Python 63/63, Go 52/52, C# 53/53).