Skip to content

TokenUsage

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

TokenUsage Class

Token usage breakdown for a single LLM call or aggregate across an agent run.

public sealed record TokenUsage : System.IEquatable<NexusLabs.Needlr.AgentFramework.Diagnostics.TokenUsage>

Inheritance System.Object 🡒 TokenUsage

Implements System.IEquatable<TokenUsage>

Example

var diagnostics = accessor.LastRunDiagnostics;
var usage = diagnostics.AggregateTokenUsage;
Console.WriteLine($"Input: {usage.InputTokens} (cached: {usage.CachedInputTokens})");
Console.WriteLine($"Output: {usage.OutputTokens} (reasoning: {usage.ReasoningTokens})");
Console.WriteLine($"Total: {usage.TotalTokens}");

Remarks

Each ChatCompletionDiagnostics carries a TokenUsage for that individual call. AggregateTokenUsage sums across all calls in one agent run. AggregateTokenUsage sums across all stages in a pipeline.

Token counts come from the LLM provider's response metadata. If the provider does not report a field, the corresponding value is 0.

Constructors

TokenUsage(long, long, long, long, long) Constructor

Token usage breakdown for a single LLM call or aggregate across an agent run.

public TokenUsage(long InputTokens, long OutputTokens, long TotalTokens, long CachedInputTokens, long ReasoningTokens);

Parameters

InputTokens System.Int64

Number of tokens in the prompt sent to the model.

OutputTokens System.Int64

Number of tokens generated by the model.

TotalTokens System.Int64

Sum of input and output tokens (may include overhead tokens not in either count).

CachedInputTokens System.Int64

Subset of InputTokens served from the provider's prompt cache. Cached tokens are typically billed at a reduced rate.

ReasoningTokens System.Int64

Tokens consumed by chain-of-thought reasoning (e.g., OpenAI o-series models). Zero for models that do not report reasoning tokens.

Example

var diagnostics = accessor.LastRunDiagnostics;
var usage = diagnostics.AggregateTokenUsage;
Console.WriteLine($"Input: {usage.InputTokens} (cached: {usage.CachedInputTokens})");
Console.WriteLine($"Output: {usage.OutputTokens} (reasoning: {usage.ReasoningTokens})");
Console.WriteLine($"Total: {usage.TotalTokens}");

Remarks

Each ChatCompletionDiagnostics carries a TokenUsage for that individual call. AggregateTokenUsage sums across all calls in one agent run. AggregateTokenUsage sums across all stages in a pipeline.

Token counts come from the LLM provider's response metadata. If the provider does not report a field, the corresponding value is 0.

Properties

TokenUsage.CachedInputTokens Property

Subset of InputTokens served from the provider's prompt cache. Cached tokens are typically billed at a reduced rate.

public long CachedInputTokens { get; init; }

Property Value

System.Int64

TokenUsage.InputTokens Property

Number of tokens in the prompt sent to the model.

public long InputTokens { get; init; }

Property Value

System.Int64

TokenUsage.OutputTokens Property

Number of tokens generated by the model.

public long OutputTokens { get; init; }

Property Value

System.Int64

TokenUsage.ReasoningTokens Property

Tokens consumed by chain-of-thought reasoning (e.g., OpenAI o-series models). Zero for models that do not report reasoning tokens.

public long ReasoningTokens { get; init; }

Property Value

System.Int64

TokenUsage.TotalTokens Property

Sum of input and output tokens (may include overhead tokens not in either count).

public long TotalTokens { get; init; }

Property Value

System.Int64