# RunStatistics

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.runstatistics/
> Summary: RunStatistics: A summary of the runs in a time range.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

A summary of the runs in a time range.

```csharp
public sealed record RunStatistics : IEquatable<RunStatistics>
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.runstatistics/">RunStatistics</a></dd><dt>Implements</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.iequatable-1">IEquatable&lt;RunStatistics&gt;</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Remarks

Token totals cover only runs that reported usage information. If a
provider does not return usage, that run is counted but contributes
nothing to the token total.

Cost is populated only when pricing is configured — see
`TotalCost`. Pricing is not embedded in Tracon: it comes from
the model catalog or the `Tracon:Pricing` configuration.

## Constructors

### <a id="Tracon_RunStatistics__ctor"></a> RunStatistics\(\)

```csharp
public RunStatistics()
```

## Properties

### <a id="Tracon_RunStatistics_AudioInputTokens"></a> AudioInputTokens

The audio input tokens. Counted INSIDE `InputTokens`.

```csharp
public long AudioInputTokens { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_AudioOutputTokens"></a> AudioOutputTokens

The audio output tokens. Counted INSIDE `OutputTokens`.

```csharp
public long AudioOutputTokens { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_AwaitingInputRuns"></a> AwaitingInputRuns

The number of runs awaiting human input.

```csharp
public long AwaitingInputRuns { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

#### Remarks

Occurs only in workflow runs. Counted separately because such a run is
neither running nor settled; forcing it into one bucket would make the
subtotals not add up to `TotalRuns`.

### <a id="Tracon_RunStatistics_ByAgent"></a> ByAgent

The breakdown by agent.

```csharp
public IReadOnlyList<RunAgentStatistics> ByAgent { get; init; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[RunAgentStatistics](/api/tracon.runagentstatistics/)\>

### <a id="Tracon_RunStatistics_ByErrorClass"></a> ByErrorClass

The breakdown by error class. Only runs that ended in an error are
counted. Rows written before the error class was added appear in the
`Unknown` bucket (past rows are not backfilled).

```csharp
public IReadOnlyList<RunErrorStatistics> ByErrorClass { get; init; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[RunErrorStatistics](/api/tracon.runerrorstatistics/)\>

### <a id="Tracon_RunStatistics_ByLabel"></a> ByLabel

The breakdown by label. One entry per distinct key/value pair, so a run
carrying three labels contributes to three entries.

```csharp
public IReadOnlyList<RunLabelStatistics> ByLabel { get; init; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[RunLabelStatistics](/api/tracon.runlabelstatistics/)\>

#### Remarks

The entries therefore do not sum to `TotalRuns`, unlike
[RunStatistics.ByAgent](/api/tracon.runstatistics/#Tracon_RunStatistics_ByAgent): a label set is not a partition of the runs.
Bounded by [RunStatisticsQuery.MaxAgents](/api/tracon.runstatisticsquery/#Tracon_RunStatisticsQuery_MaxAgents).

### <a id="Tracon_RunStatistics_ByModel"></a> ByModel

The breakdown by model. Runs with an unknown model name do not appear
in this list; they are still counted in the totals.

```csharp
public IReadOnlyList<RunModelStatistics> ByModel { get; init; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[RunModelStatistics](/api/tracon.runmodelstatistics/)\>

### <a id="Tracon_RunStatistics_ByUser"></a> ByUser

The breakdown by user. Runs that carry no user identity do not appear
in this list; they are still counted in the totals.

```csharp
public IReadOnlyList<RunUserStatistics> ByUser { get; init; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[RunUserStatistics](/api/tracon.runuserstatistics/)\>

#### Remarks

Bounded by [RunStatisticsQuery.MaxAgents](/api/tracon.runstatisticsquery/#Tracon_RunStatisticsQuery_MaxAgents), users with the
highest run count first. Rows written before the column existed carry no
user and therefore never appear here (no backfill).

### <a id="Tracon_RunStatistics_ByVersion"></a> ByVersion

The breakdown by definition version. Runs with an unknown version do not appear in this list.

```csharp
public IReadOnlyList<RunVersionStatistics> ByVersion { get; init; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[RunVersionStatistics](/api/tracon.runversionstatistics/)\>

### <a id="Tracon_RunStatistics_CachedInputTokens"></a> CachedInputTokens

The input tokens that were served from the prompt cache. Counted INSIDE
`InputTokens`, so the two must not be added together.

```csharp
public long CachedInputTokens { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

#### Remarks

Runs whose provider does not report cache usage contribute nothing here,
exactly as a run that reports no usage contributes nothing to
[RunStatistics.TotalTokens](/api/tracon.runstatistics/#Tracon_RunStatistics_TotalTokens).

### <a id="Tracon_RunStatistics_CanceledRuns"></a> CanceledRuns

The number of cancelled runs.

```csharp
public required long CanceledRuns { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_CompletedRuns"></a> CompletedRuns

The number of runs that completed successfully.

```csharp
public required long CompletedRuns { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_Currency"></a> Currency

The currency. Populated when `TotalCost` is populated.

```csharp
public string? Currency { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_RunStatistics_CurrencyCount"></a> CurrencyCount

The number of currencies the matched runs are priced in.

```csharp
public int CurrencyCount { get; init; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

#### Remarks

Amounts in two currencies are never added. Above one, `TotalCost` and
`Currency` are [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null), and so is the cost of every breakdown
([RunStatistics.ByModel](/api/tracon.runstatistics/#Tracon_RunStatistics_ByModel), [RunStatistics.ByUser](/api/tracon.runstatistics/#Tracon_RunStatistics_ByUser), [RunStatistics.ByLabel](/api/tracon.runstatistics/#Tracon_RunStatistics_ByLabel)): a breakdown
carries no currency of its own, so its sum could not say which one it is in.
Currencies are compared without regard to letter case.

### <a id="Tracon_RunStatistics_ErrorRate"></a> ErrorRate

The error rate among settled runs (0–1). [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) if no
run has settled.

```csharp
public double? ErrorRate { get; }
```

#### Property Value

 [double](https://learn.microsoft.com/dotnet/api/system.double)?

#### Remarks

The denominator is *settled* runs, not `TotalRuns`.
Whether a run in progress will succeed or fail is not yet known;
including it in the denominator would artificially lower the rate.

### <a id="Tracon_RunStatistics_FailedRuns"></a> FailedRuns

The number of runs that ended in an error.

```csharp
public required long FailedRuns { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_InputTokens"></a> InputTokens

The total input tokens.

```csharp
public long InputTokens { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_OutputTokens"></a> OutputTokens

The total output tokens.

```csharp
public long OutputTokens { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_PositiveRate"></a> PositiveRate

The positive rate among [RunScoreKind.Binary](/api/tracon.runscorekind/) scores (0–1).
Star ratings are not included in this rate — averaging the two kinds
would be meaningless. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) if there is no binary score.

```csharp
public double? PositiveRate { get; init; }
```

#### Property Value

 [double](https://learn.microsoft.com/dotnet/api/system.double)?

### <a id="Tracon_RunStatistics_ReasoningTokens"></a> ReasoningTokens

The tokens spent on reasoning. Counted INSIDE `OutputTokens`.

```csharp
public long ReasoningTokens { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_RunningRuns"></a> RunningRuns

The number of runs still running.

```csharp
public required long RunningRuns { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_RunsWithUnknownPricing"></a> RunsWithUnknownPricing

The number of runs whose model is known but whose pricing is undefined.

```csharp
public long RunsWithUnknownPricing { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_ScoredRuns"></a> ScoredRuns

The number of runs that received at least one [RunScore](/api/tracon.runscore/)
(at the run or message level). Eval runs ([RunKind.Eval](/api/tracon.runkind/))
are excluded for the same reason as `TotalRuns`.

```csharp
public long ScoredRuns { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_TotalCost"></a> TotalCost

The total cost. If a model has undefined pricing, that model's run
costs are **not included** in this total (only runs with
known pricing are summed); the number of runs excluded appears in
`RunsWithUnknownPricing`. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) if no run
was ever priced.

```csharp
public decimal? TotalCost { get; init; }
```

#### Property Value

 [decimal](https://learn.microsoft.com/dotnet/api/system.decimal)?

### <a id="Tracon_RunStatistics_TotalRuns"></a> TotalRuns

The total number of runs matching the filter.

```csharp
public required long TotalRuns { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunStatistics_TotalTokens"></a> TotalTokens

The total tokens.

```csharp
public long TotalTokens { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

## Methods

### <a id="Tracon_RunStatistics_Equals_System_Object_"></a> Equals\(object?\)

```csharp
public override bool Equals(object? obj)
```

#### Parameters

`obj` [object](https://learn.microsoft.com/dotnet/api/system.object)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_RunStatistics_Equals_Tracon_RunStatistics_"></a> Equals\(RunStatistics?\)

```csharp
public bool Equals(RunStatistics? other)
```

#### Parameters

`other` [RunStatistics](/api/tracon.runstatistics/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_RunStatistics_GetHashCode"></a> GetHashCode\(\)

```csharp
public override int GetHashCode()
```

#### Returns

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

### <a id="Tracon_RunStatistics_ToString"></a> ToString\(\)

```csharp
public override string ToString()
```

#### Returns

 [string](https://learn.microsoft.com/dotnet/api/system.string)

## Operators

### <a id="Tracon_RunStatistics_op_Equality_Tracon_RunStatistics_Tracon_RunStatistics_"></a> operator ==\(RunStatistics?, RunStatistics?\)

```csharp
public static bool operator ==(RunStatistics? left, RunStatistics? right)
```

#### Parameters

`left` [RunStatistics](/api/tracon.runstatistics/)?

`right` [RunStatistics](/api/tracon.runstatistics/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_RunStatistics_op_Inequality_Tracon_RunStatistics_Tracon_RunStatistics_"></a> operator \!=\(RunStatistics?, RunStatistics?\)

```csharp
public static bool operator !=(RunStatistics? left, RunStatistics? right)
```

#### Parameters

`left` [RunStatistics](/api/tracon.runstatistics/)?

`right` [RunStatistics](/api/tracon.runstatistics/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)