# How to Read Token Counts, Context Window Utilization, and Billing Info in the Copilot SDK

> Understand token counts, context window, and billing in the Copilot SDK. Learn how to access model metadata and real-time usage events for precise control over your AI integrations.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: how-to-guide
- Published: 2026-08-02

---

**The Copilot SDK exposes token counts and billing data through `ModelBilling` metadata on available models and real-time `session.usage` events that report per-request consumption and context limits.**

The GitHub Copilot SDK provides granular visibility into token consumption and cost management through type-safe TypeScript interfaces. Developers can query model-specific pricing tiers and context window limits before initiating sessions, then monitor actual usage through event-driven callbacks. This guide demonstrates how to access billing information, track context utilization, and calculate costs using the actual source structures found in `github/copilot-sdk`.

## Understanding the Data Sources

The SDK surfaces usage and billing information through two distinct mechanisms that work together to provide a complete cost picture.

**Model Metadata (`ModelBilling`)**: Available via `client.getAvailableModels()`, each model description contains a `billing` object that defines per-token-batch pricing and context window limits. According to the source code in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) (lines 9125-9140), the `ModelBilling` interface includes `tokenPrices` with `inputPrice`, `outputPrice`, and `maxPromptTokens` fields, plus an optional `longContext` tier for extended windows.

**Session Usage Events**: While a session runs, the SDK emits `session.usage` events containing real-time token consumption. These events implement the `AssistantUsageEvent` interface defined in [`nodejs/src/generated/session-events.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/session-events.ts) (lines 2184-2190), providing `tokenCount`, `contextMax`, and detailed `tokenDetails` breakdowns. For cumulative tracking, the `session.usage_checkpoint` event (lines 2220-2240) emits `UsageCheckpointEvent` data containing aggregated totals for the entire session.

Both sources respect the account's billing mode, indicated by the `token_based_billing` boolean found in quota snapshots within [`rpc.ts`](https://github.com/github/copilot-sdk/blob/main/rpc.ts) (lines 2831-2833).

## Retrieving Model-Level Billing and Context Limits

Before starting a session, inspect the `ModelBilling` data to understand pricing tiers and maximum context windows. This data lives in the `billing` field of each model returned by `getAvailableModels()`.

```typescript
import { CopilotClient } from '@github/copilot-sdk';

const client = new CopilotClient({ token: process.env.COPILOT_TOKEN });

async function listModelBilling() {
  const models = await client.getAvailableModels();
  
  for (const model of models) {
    const billing = model.billing;
    if (!billing?.tokenPrices) continue;

    console.log(`Model: ${model.id}`);
    console.log(`  Default context max: ${billing.tokenPrices.maxPromptTokens}`);
    console.log(`  Long-context max: ${billing.tokenPrices.longContext?.maxPromptTokens}`);
    console.log(`  Input price/batch: ${billing.tokenPrices.inputPrice}`);
    console.log(`  Output price/batch: ${billing.tokenPrices.outputPrice}`);
  }
}

listModelBilling();

```

The `ModelBillingTokenPrices` interface defines the `batchSize` property (typically representing the number of tokens per billing unit), which you will need later when calculating actual costs from raw token counts.

## Monitoring Per-Request Token Usage and Context Utilization

During an active session, listen for `session.usage` events to track individual request consumption and verify context window utilization. These events fire immediately after each Copilot completion request.

```typescript
async function monitorUsage() {
  const session = await client.startSession({ modelId: 'gpt-4' });

  session.on('session.usage', (event) => {
    // event implements AssistantUsageEvent
    console.log('Request token count:', event.tokenCount);
    console.log('Context limit for this tier:', event.contextMax);
    console.log('Token breakdown:', event.tokenDetails);
    
    // Calculate utilization percentage
    const utilization = (event.tokenCount / event.contextMax) * 100;
    console.log(`Context window utilization: ${utilization.toFixed(1)}%`);
  });

  // Continue with normal session operations...
  // await session.prompt('Explain this code...');
}

monitorUsage();

```

The `contextMax` field reflects the specific tier's limit (default or long-context) based on the model configuration, while `tokenDetails` provides optional categorization of prompt versus completion tokens.

## Tracking Cumulative Usage with Checkpoints

For long-running sessions or accurate billing aggregation, consume the `session.usage_checkpoint` event. This emits a `UsageCheckpointEvent` containing cumulative totals since session start, ideal for resumable sessions or periodic cost reporting.

```typescript
async function trackCheckpoint() {
  const session = await client.startSession({ modelId: 'gpt-4' });

  session.on('session.usage_checkpoint', (checkpoint) => {
    // checkpoint.data contains aggregated totals
    console.log('Cumulative input tokens:', checkpoint.data.totalInputTokens);
    console.log('Cumulative output tokens:', checkpoint.data.totalOutputTokens);
    
    // Store these values for external billing aggregation
    const sessionTotals = {
      input: checkpoint.data.totalInputTokens,
      output: checkpoint.data.totalOutputTokens,
      timestamp: checkpoint.timestamp
    };
  });
}

trackCheckpoint();

```

Unlike per-request events, checkpoints provide a definitive running total that accounts for all tokens consumed in the session up to that point, eliminating the need to sum individual requests manually.

## Calculating Real-Time Costs

Combine model metadata with checkpoint data to compute actual AI credit costs. The calculation requires dividing token counts by the billing batch size, then multiplying by the respective input and output prices.

```typescript
async function calculateAccumulatedCost() {
  // Cache billing info for cost calculation
  const models = await client.getAvailableModels();
  const billingMap = new Map(
    models.map(m => [m.id, m.billing?.tokenPrices])
  );

  const session = await client.startSession({ modelId: 'gpt-4' });
  const prices = billingMap.get('gpt-4');
  
  if (!prices) throw new Error('Billing info unavailable');

  session.on('session.usage_checkpoint', (ckpt) => {
    const { inputPrice = 0, outputPrice = 0, batchSize = 1 } = prices;
    
    const inputBatches = Math.ceil(ckpt.data.totalInputTokens / batchSize);
    const outputBatches = Math.ceil(ckpt.data.totalOutputTokens / batchSize);
    
    const totalCost = (inputBatches * inputPrice) + (outputBatches * outputPrice);
    
    console.log(`Accumulated AI credits: ${totalCost}`);
    console.log(`Billing method: ${prices.tokenBasedBilling ? 'Per-token' : 'Request-based'}`);
  });
}

calculateAccumulatedCost();

```

This approach accounts for the batch-based pricing model where costs are calculated per fixed-size token batch rather than per individual token.

## Summary

- **Query `ModelBilling` first**: Call `client.getAvailableModels()` to retrieve pricing tiers (`inputPrice`, `outputPrice`) and context limits (`maxPromptTokens`, `longContext.maxPromptTokens`) from [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts).
- **Monitor `session.usage` events**: Listen during active sessions to capture per-request `tokenCount`, `contextMax`, and `tokenDetails` via the `AssistantUsageEvent` interface in [`nodejs/src/generated/session-events.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/session-events.ts).
- **Aggregate with checkpoints**: Use `session.usage_checkpoint` events to get cumulative `totalInputTokens` and `totalOutputTokens` without manual summation.
- **Calculate costs by batch**: Divide token totals by `batchSize` from `ModelBillingTokenPrices`, multiply by respective prices, and sum for total AI credits consumed.
- **Check billing mode**: Verify `token_based_billing` on quota snapshots to determine if the account uses token-based or request-based billing.

## Frequently Asked Questions

### How do I check if my account uses token-based billing versus request-based billing?

Inspect the quota snapshot returned by the SDK for the `token_based_billing` boolean field. According to [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) (lines 2831-2833), this flag indicates whether the account consumes AI credits per token or uses a fixed premium-request quota. This determines whether you need to calculate costs using the batch pricing method or simply count requests.

### What is the difference between `contextMax` and `maxPromptTokens`?

`maxPromptTokens` (found in `ModelBilling`) defines the absolute maximum tokens the model accepts for a given tier, while `contextMax` (found in `AssistantUsageEvent`) reflects the actual limit applied to the current request. The latter may vary based on dynamic constraints or specific model configurations during the session, whereas the former is a static property of the billing tier.

### When should I use `session.usage_checkpoint` instead of summing `session.usage` events?

Use `session.usage_checkpoint` when you need authoritative cumulative totals for resumable sessions, billing aggregation, or when network reliability might cause you to miss individual usage events. The checkpoint event provides a ground-truth snapshot of `totalInputTokens` and `totalOutputTokens` that accounts for all activity up to that point, eliminating drift from missed events.

### Where are the TypeScript interfaces for billing and usage events defined?

The `ModelBilling` and `ModelBillingTokenPrices` interfaces reside in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) (around lines 9125-9140), while usage event types like `AssistantUsageEvent` and `UsageCheckpointEvent` are defined in [`nodejs/src/generated/session-events.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/session-events.ts) (lines 2184-2190 and 2220-2240 respectively). These generated files contain the authoritative schema for all billing and token count fields.