> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/17.latest/reference/services/ai-usage-analytics-service.md).

# IAIUsageAnalyticsService

Service for querying aggregated AI usage statistics derived from audit logs.

## Namespace

```csharp
using Umbraco.AI.Core.Analytics.Usage;
```

## Interface

{% code title="IAIUsageAnalyticsService" %}

```csharp
public interface IAIUsageAnalyticsService
{
    Task<AIUsageSummary> GetSummaryAsync(
        DateTime from,
        DateTime to,
        AIUsagePeriod? requestedGranularity = null,
        AIUsageFilter? filter = null,
        CancellationToken cancellationToken = default);

    Task<IEnumerable<AIUsageTimeSeriesPoint>> GetTimeSeriesAsync(
        DateTime from,
        DateTime to,
        AIUsagePeriod? requestedGranularity = null,
        AIUsageFilter? filter = null,
        CancellationToken cancellationToken = default);

    Task<IEnumerable<AIUsageBreakdownItem>> GetBreakdownByProviderAsync(
        DateTime from,
        DateTime to,
        AIUsagePeriod? requestedGranularity = null,
        CancellationToken cancellationToken = default);

    Task<IEnumerable<AIUsageBreakdownItem>> GetBreakdownByModelAsync(
        DateTime from,
        DateTime to,
        AIUsagePeriod? requestedGranularity = null,
        CancellationToken cancellationToken = default);

    Task<IEnumerable<AIUsageBreakdownItem>> GetBreakdownByProfileAsync(
        DateTime from,
        DateTime to,
        AIUsagePeriod? requestedGranularity = null,
        CancellationToken cancellationToken = default);

    Task<IEnumerable<AIUsageBreakdownItem>> GetBreakdownByUserAsync(
        DateTime from,
        DateTime to,
        AIUsagePeriod? requestedGranularity = null,
        CancellationToken cancellationToken = default);
}
```

{% endcode %}

## Methods

### GetSummaryAsync

Gets aggregated usage statistics for a time period.

| Parameter              | Type                | Description        |
| ---------------------- | ------------------- | ------------------ |
| `from`                 | `DateTime`          | Start of period    |
| `to`                   | `DateTime`          | End of period      |
| `requestedGranularity` | `AIUsagePeriod?`    | Data granularity   |
| `filter`               | `AIUsageFilter?`    | Optional filter    |
| `cancellationToken`    | `CancellationToken` | Cancellation token |

**Returns**: `AIUsageSummary` with totals and averages.

{% code title="Example" %}

```csharp
var summary = await _analyticsService.GetSummaryAsync(
    from: DateTime.UtcNow.AddDays(-30),
    to: DateTime.UtcNow);

Console.WriteLine($"Total Requests: {summary.TotalRequests}");
Console.WriteLine($"Total Tokens: {summary.TotalTokens:N0}");
Console.WriteLine($"Success Rate: {summary.SuccessRate:P1}");
Console.WriteLine($"Avg Duration: {summary.AverageDurationMs}ms");
```

{% endcode %}

### GetTimeSeriesAsync

Gets usage metrics over time for trend analysis.

| Parameter              | Type                | Description        |
| ---------------------- | ------------------- | ------------------ |
| `from`                 | `DateTime`          | Start of period    |
| `to`                   | `DateTime`          | End of period      |
| `requestedGranularity` | `AIUsagePeriod?`    | Time interval      |
| `filter`               | `AIUsageFilter?`    | Optional filter    |
| `cancellationToken`    | `CancellationToken` | Cancellation token |

**Returns**: Time series data points.

{% code title="Example" %}

```csharp
var timeSeries = await _analyticsService.GetTimeSeriesAsync(
    from: DateTime.UtcNow.AddDays(-7),
    to: DateTime.UtcNow,
    requestedGranularity: AIUsagePeriod.Daily);

foreach (var point in timeSeries)
{
    Console.WriteLine($"{point.Timestamp:d}: {point.RequestCount} requests, {point.TotalTokens:N0} tokens");
}
```

{% endcode %}

### GetBreakdownByProviderAsync

Gets usage distribution by AI provider.

{% code title="Example" %}

```csharp
var byProvider = await _analyticsService.GetBreakdownByProviderAsync(
    from: DateTime.UtcNow.AddDays(-30),
    to: DateTime.UtcNow);

foreach (var item in byProvider.OrderByDescending(x => x.Percentage))
{
    Console.WriteLine($"{item.DimensionName}: {item.Percentage:P0} ({item.TotalTokens:N0} tokens)");
}
```

{% endcode %}

### GetBreakdownByModelAsync

Gets usage distribution by AI model.

{% code title="Example" %}

```csharp
var byModel = await _analyticsService.GetBreakdownByModelAsync(
    from: DateTime.UtcNow.AddDays(-30),
    to: DateTime.UtcNow);
```

{% endcode %}

### GetBreakdownByProfileAsync

Gets usage distribution by profile.

{% code title="Example" %}

```csharp
var byProfile = await _analyticsService.GetBreakdownByProfileAsync(
    from: DateTime.UtcNow.AddDays(-30),
    to: DateTime.UtcNow);
```

{% endcode %}

### GetBreakdownByUserAsync

Gets usage distribution by user.

{% code title="Example" %}

```csharp
var byUser = await _analyticsService.GetBreakdownByUserAsync(
    from: DateTime.UtcNow.AddDays(-30),
    to: DateTime.UtcNow);
```

{% endcode %}

## Model Classes

### AIUsageSummary

| Property            | Type     | Description             |
| ------------------- | -------- | ----------------------- |
| `TotalRequests`     | `int`    | Number of operations    |
| `InputTokens`       | `long`   | Total input tokens      |
| `OutputTokens`      | `long`   | Total output tokens     |
| `TotalTokens`       | `long`   | Combined tokens         |
| `SuccessCount`      | `int`    | Successful operations   |
| `FailureCount`      | `int`    | Failed operations       |
| `SuccessRate`       | `double` | Success ratio (0.0-1.0) |
| `AverageDurationMs` | `int`    | Average operation time  |

### AIUsageTimeSeriesPoint

| Property       | Type       | Description          |
| -------------- | ---------- | -------------------- |
| `Timestamp`    | `DateTime` | Interval start       |
| `RequestCount` | `int`      | Requests in interval |
| `InputTokens`  | `long`     | Input tokens         |
| `OutputTokens` | `long`     | Output tokens        |
| `TotalTokens`  | `long`     | Total tokens         |
| `SuccessCount` | `int`      | Successes            |
| `FailureCount` | `int`      | Failures             |

### AIUsageBreakdownItem

| Property        | Type      | Description    |
| --------------- | --------- | -------------- |
| `Dimension`     | `string`  | Identifier     |
| `DimensionName` | `string?` | Display name   |
| `RequestCount`  | `int`     | Requests       |
| `TotalTokens`   | `long`    | Tokens used    |
| `Percentage`    | `double`  | Share of total |

### AIUsagePeriod

| Value    | Description      |
| -------- | ---------------- |
| `Hourly` | Hourly intervals |
| `Daily`  | Daily intervals  |

## Usage Example

{% code title="UsageDashboard.cs" %}

```csharp
public class UsageDashboard
{
    private readonly IAIUsageAnalyticsService _analyticsService;

    public UsageDashboard(IAIUsageAnalyticsService analyticsService)
    {
        _analyticsService = analyticsService;
    }

    public async Task<DashboardData> GetDashboardDataAsync()
    {
        var from = DateTime.UtcNow.AddDays(-30);
        var to = DateTime.UtcNow;

        var summary = await _analyticsService.GetSummaryAsync(from, to);
        var timeSeries = await _analyticsService.GetTimeSeriesAsync(from, to);
        var byProvider = await _analyticsService.GetBreakdownByProviderAsync(from, to);
        var byProfile = await _analyticsService.GetBreakdownByProfileAsync(from, to);

        return new DashboardData
        {
            Summary = summary,
            DailyTrend = timeSeries.ToList(),
            ProviderDistribution = byProvider.ToList(),
            ProfileDistribution = byProfile.ToList()
        };
    }
}
```

{% endcode %}

## Related

* [Usage Analytics Backoffice](/ai-in-umbraco/17.latest/backoffice/usage-analytics.md) - Viewing analytics
* [Audit Logs](/ai-in-umbraco/17.latest/reference/services/ai-audit-log-service.md) - Raw audit data


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/ai-in-umbraco/17.latest/reference/services/ai-usage-analytics-service.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.