fix(admin): 修复 usage 观测全表扫描并下推聚合查询

- 收紧 admin usage/stats 默认时间范围和 active 轮询查询
- 将 summary/records/aggregation/time-series/leaderboard 下推到 SQL 侧
- 统一前端时间参数并补齐 admin usage/stats 回归测试

apps/aether-gateway/src/data/state/runtime.rs

@@ -666,6 +666,68 @@ impl GatewayDataState {
         }
     }
 
+    pub(crate) async fn count_usage_audits(
+        &self,
+        query: &UsageAuditListQuery,
+    ) -> Result<u64, DataLayerError> {
+        match &self.usage_reader {
+            Some(repository) => repository.count_usage_audits(query).await,
+            None => Ok(0),
+        }
+    }
+
+    pub(crate) async fn aggregate_usage_audits(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageAuditAggregationQuery,
+    ) -> Result<
+        Vec<aether_data_contracts::repository::usage::StoredUsageAuditAggregation>,
+        DataLayerError,
+    > {
+        match &self.usage_reader {
+            Some(repository) => repository.aggregate_usage_audits(query).await,
+            None => Ok(Vec::new()),
+        }
+    }
+
+    pub(crate) async fn summarize_usage_audits(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageAuditSummaryQuery,
+    ) -> Result<aether_data_contracts::repository::usage::StoredUsageAuditSummary, DataLayerError>
+    {
+        match &self.usage_reader {
+            Some(repository) => repository.summarize_usage_audits(query).await,
+            None => {
+                Ok(aether_data_contracts::repository::usage::StoredUsageAuditSummary::default())
+            }
+        }
+    }
+
+    pub(crate) async fn summarize_usage_time_series(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageTimeSeriesQuery,
+    ) -> Result<
+        Vec<aether_data_contracts::repository::usage::StoredUsageTimeSeriesBucket>,
+        DataLayerError,
+    > {
+        match &self.usage_reader {
+            Some(repository) => repository.summarize_usage_time_series(query).await,
+            None => Ok(Vec::new()),
+        }
+    }
+
+    pub(crate) async fn summarize_usage_leaderboard(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageLeaderboardQuery,
+    ) -> Result<
+        Vec<aether_data_contracts::repository::usage::StoredUsageLeaderboardSummary>,
+        DataLayerError,
+    > {
+        match &self.usage_reader {
+            Some(repository) => repository.summarize_usage_leaderboard(query).await,
+            None => Ok(Vec::new()),
+        }
+    }
+
     pub(crate) async fn summarize_usage_daily_heatmap(
         &self,
         query: &UsageDailyHeatmapQuery,

apps/aether-gateway/src/handlers/admin/observability/stats/analytics_routes.rs

@@ -1,4 +1,5 @@
 use super::range::build_comparison_range;
+use super::resolve_admin_usage_time_range;
 use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
 use crate::handlers::admin::shared::query_param_value;
 use crate::GatewayError;
@@ -6,17 +7,29 @@ use aether_admin::observability::stats::{
     admin_stats_bad_request_response, admin_stats_comparison_empty_response,
     admin_stats_error_distribution_empty_response,
     admin_stats_performance_percentiles_empty_response, admin_stats_time_series_empty_response,
-    build_admin_stats_comparison_response, build_admin_stats_error_distribution_response,
-    build_admin_stats_performance_percentiles_response, build_admin_stats_time_series_response,
+    build_admin_stats_comparison_response_from_aggregates,
+    build_admin_stats_error_distribution_response,
+    build_admin_stats_performance_percentiles_response,
+    build_admin_stats_time_series_response_from_summaries, AdminStatsAggregate,
     AdminStatsComparisonType, AdminStatsGranularity, AdminStatsTimeRange, AdminStatsUsageFilter,
 };
-use axum::{
-    body::Body,
-    http,
-    response::{IntoResponse, Response},
-    Json,
+use aether_data_contracts::repository::usage::{
+    UsageAuditSummaryQuery, UsageTimeSeriesGranularity, UsageTimeSeriesQuery,
 };
-use serde_json::json;
+use axum::{body::Body, http, response::Response};
+
+fn usage_summary_to_admin_stats_aggregate(
+    summary: &aether_data_contracts::repository::usage::StoredUsageAuditSummary,
+) -> AdminStatsAggregate {
+    AdminStatsAggregate {
+        total_requests: summary.total_requests,
+        total_tokens: summary.recorded_total_tokens,
+        total_cost: summary.total_cost_usd,
+        actual_total_cost: summary.actual_total_cost_usd,
+        total_response_time_ms: summary.total_response_time_ms,
+        error_requests: summary.error_requests,
+    }
+}
 
 pub(super) async fn maybe_build_local_admin_stats_analytics_response(
     state: &AdminAppState<'_>,
@@ -58,15 +71,39 @@ pub(super) async fn maybe_build_local_admin_stats_analytics_response(
                 &comparison_range,
             )));
         }
-        let current_usage = state
-            .list_admin_usage_for_range(&current_range, &AdminStatsUsageFilter::default())
+        let Some((current_from_unix_secs, current_until_unix_secs)) =
+            current_range.to_unix_bounds()
+        else {
+            return Ok(Some(admin_stats_comparison_empty_response(
+                &current_range,
+                &comparison_range,
+            )));
+        };
+        let Some((comparison_from_unix_secs, comparison_until_unix_secs)) =
+            comparison_range.to_unix_bounds()
+        else {
+            return Ok(Some(admin_stats_comparison_empty_response(
+                &current_range,
+                &comparison_range,
+            )));
+        };
+        let current_summary = state
+            .summarize_usage_audits(&UsageAuditSummaryQuery {
+                created_from_unix_secs: current_from_unix_secs,
+                created_until_unix_secs: current_until_unix_secs,
+                ..Default::default()
+            })
             .await?;
-        let comparison_usage = state
-            .list_admin_usage_for_range(&comparison_range, &AdminStatsUsageFilter::default())
+        let comparison_summary = state
+            .summarize_usage_audits(&UsageAuditSummaryQuery {
+                created_from_unix_secs: comparison_from_unix_secs,
+                created_until_unix_secs: comparison_until_unix_secs,
+                ..Default::default()
+            })
             .await?;
-        return Ok(Some(build_admin_stats_comparison_response(
-            &current_usage,
-            &comparison_usage,
+        return Ok(Some(build_admin_stats_comparison_response_from_aggregates(
+            &usage_summary_to_admin_stats_aggregate(&current_summary),
+            &usage_summary_to_admin_stats_aggregate(&comparison_summary),
             &current_range,
             &comparison_range,
         )));
@@ -79,19 +116,9 @@ pub(super) async fn maybe_build_local_admin_stats_analytics_response(
             "/api/admin/stats/errors/distribution" | "/api/admin/stats/errors/distribution/"
         )
     {
-        let Some(time_range) =
-            (match AdminStatsTimeRange::resolve_optional(request_context.query_string()) {
+        let time_range = match resolve_admin_usage_time_range(request_context.query_string()) {
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
-            })
-        else {
-            return Ok(Some(
-                Json(json!({
-                    "distribution": [],
-                    "trend": [],
-                }))
-                .into_response(),
-            ));
         };
         if !state.has_usage_data_reader() {
             return Ok(Some(admin_stats_error_distribution_empty_response()));
@@ -114,13 +141,9 @@ pub(super) async fn maybe_build_local_admin_stats_analytics_response(
                 | "/api/admin/stats/performance/percentiles/"
         )
     {
-        let Some(time_range) =
-            (match AdminStatsTimeRange::resolve_optional(request_context.query_string()) {
+        let time_range = match resolve_admin_usage_time_range(request_context.query_string()) {
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
-            })
-        else {
-            return Ok(Some(Json(json!([])).into_response()));
         };
         if !state.has_usage_data_reader() {
             return Ok(Some(admin_stats_performance_percentiles_empty_response()));
@@ -146,13 +169,9 @@ pub(super) async fn maybe_build_local_admin_stats_analytics_response(
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
         };
-        let Some(time_range) =
-            (match AdminStatsTimeRange::resolve_optional(request_context.query_string()) {
+        let time_range = match resolve_admin_usage_time_range(request_context.query_string()) {
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
-            })
-        else {
-            return Ok(Some(Json(json!([])).into_response()));
         };
         if let Err(detail) = time_range.validate_for_time_series(granularity) {
             return Ok(Some(admin_stats_bad_request_response(detail)));
@@ -162,13 +181,31 @@ pub(super) async fn maybe_build_local_admin_stats_analytics_response(
         }
 
         let filters = AdminStatsUsageFilter::from_query(request_context.query_string());
-        let usage = state
-            .list_admin_usage_for_range(&time_range, &filters)
+        let query_granularity = match granularity {
+            AdminStatsGranularity::Hour => UsageTimeSeriesGranularity::Hour,
+            AdminStatsGranularity::Day
+            | AdminStatsGranularity::Week
+            | AdminStatsGranularity::Month => UsageTimeSeriesGranularity::Day,
+        };
+        let Some((created_from_unix_secs, created_until_unix_secs)) = time_range.to_unix_bounds()
+        else {
+            return Ok(Some(admin_stats_time_series_empty_response()));
+        };
+        let buckets = state
+            .summarize_usage_time_series(&UsageTimeSeriesQuery {
+                created_from_unix_secs,
+                created_until_unix_secs,
+                granularity: query_granularity,
+                tz_offset_minutes: time_range.tz_offset_minutes,
+                user_id: filters.user_id,
+                provider_name: filters.provider_name,
+                model: filters.model,
+            })
             .await?;
-        return Ok(Some(build_admin_stats_time_series_response(
+        return Ok(Some(build_admin_stats_time_series_response_from_summaries(
             &time_range,
             granularity,
-            &usage,
+            &buckets,
         )));
     }
 

apps/aether-gateway/src/handlers/admin/observability/stats/cost_routes.rs

@@ -1,15 +1,31 @@
 use super::range::{build_time_range_from_days, parse_bounded_u32, parse_tz_offset_minutes};
+use super::resolve_admin_usage_time_range;
 use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
 use crate::handlers::admin::shared::query_param_value;
 use crate::GatewayError;
 use aether_admin::observability::stats::{
     admin_stats_bad_request_response, admin_stats_cost_forecast_empty_response,
     admin_stats_cost_savings_empty_response, build_admin_stats_cost_forecast_response,
-    build_admin_stats_cost_savings_response, AdminStatsGranularity, AdminStatsTimeRange,
-    AdminStatsUsageFilter,
+    build_admin_stats_cost_savings_response, AdminStatsGranularity, AdminStatsUsageFilter,
 };
 use axum::{body::Body, http, response::Response};
 
+fn resolve_cost_forecast_time_range(
+    query: Option<&str>,
+) -> Result<super::AdminStatsTimeRange, String> {
+    match super::AdminStatsTimeRange::resolve_optional(query)? {
+        Some(value) => Ok(value),
+        None => {
+            let tz_offset_minutes = parse_tz_offset_minutes(query)?;
+            let days = query_param_value(query, "days")
+                .map(|value| parse_bounded_u32("days", &value, 7, 365))
+                .transpose()?
+                .unwrap_or(30);
+            build_time_range_from_days(days, tz_offset_minutes)
+        }
+    }
+}
+
 pub(super) async fn maybe_build_local_admin_stats_cost_response(
     state: &AdminAppState<'_>,
     request_context: &AdminRequestContext<'_>,
@@ -34,32 +50,13 @@ pub(super) async fn maybe_build_local_admin_stats_cost_response(
             .map(|value| parse_bounded_u32("forecast_days", &value, 1, 90))
             .transpose()
         {
-            Ok(Some(value)) => value,
-            Ok(None) => 7,
+            Ok(value) => value.unwrap_or(7),
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
         };
-        let tz_offset_minutes = match parse_tz_offset_minutes(query) {
+        let time_range = match resolve_cost_forecast_time_range(query) {
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
         };
-        let time_range = match AdminStatsTimeRange::resolve_optional(query) {
-            Ok(Some(value)) => value,
-            Ok(None) => {
-                let days = match query_param_value(query, "days")
-                    .map(|value| parse_bounded_u32("days", &value, 7, 365))
-                    .transpose()
-                {
-                    Ok(Some(value)) => value,
-                    Ok(None) => 30,
-                    Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
-                };
-                match build_time_range_from_days(days, tz_offset_minutes) {
-                    Ok(value) => value,
-                    Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
-                }
-            }
-            Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
-        };
         if let Err(detail) = time_range.validate_for_time_series(AdminStatsGranularity::Day) {
             return Ok(Some(admin_stats_bad_request_response(detail)));
         }
@@ -84,13 +81,10 @@ pub(super) async fn maybe_build_local_admin_stats_cost_response(
             "/api/admin/stats/cost/savings" | "/api/admin/stats/cost/savings/"
         )
     {
-        let time_range = match AdminStatsTimeRange::resolve_optional(query) {
+        let time_range = match resolve_admin_usage_time_range(query) {
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
         };
-        if time_range.is_none() {
-            return Ok(Some(admin_stats_cost_savings_empty_response()));
-        }
         if !state.has_usage_data_reader() {
             return Ok(Some(admin_stats_cost_savings_empty_response()));
         }
@@ -101,7 +95,7 @@ pub(super) async fn maybe_build_local_admin_stats_cost_response(
             model: query_param_value(query, "model"),
         };
         let usage = state
-            .list_admin_usage_for_range(time_range.as_ref().expect("time range exists"), &filters)
+            .list_admin_usage_for_range(&time_range, &filters)
             .await?;
 
         return Ok(Some(build_admin_stats_cost_savings_response(&usage)));

apps/aether-gateway/src/handlers/admin/observability/stats/leaderboard.rs

@@ -4,9 +4,11 @@ use aether_data_contracts::repository::usage::StoredRequestUsageAudit;
 
 pub(super) use aether_admin::observability::stats::{
     build_admin_stats_leaderboard_response, build_api_key_leaderboard_items,
-    build_model_leaderboard_items, build_user_leaderboard_items, compare_leaderboard_items,
-    compute_dense_rank, AdminStatsLeaderboardItem, AdminStatsLeaderboardMetric,
-    AdminStatsLeaderboardNameMode, AdminStatsSortOrder, AdminStatsUserMetadata,
+    build_api_key_leaderboard_items_from_summaries, build_model_leaderboard_items,
+    build_model_leaderboard_items_from_summaries, build_user_leaderboard_items,
+    build_user_leaderboard_items_from_summaries, compare_leaderboard_items, compute_dense_rank,
+    AdminStatsLeaderboardItem, AdminStatsLeaderboardMetric, AdminStatsLeaderboardNameMode,
+    AdminStatsSortOrder, AdminStatsUserMetadata,
 };
 
 pub(super) async fn load_user_leaderboard_metadata(

apps/aether-gateway/src/handlers/admin/observability/stats/leaderboard_routes.rs

@@ -1,16 +1,18 @@
 use super::leaderboard::{
-    build_admin_stats_leaderboard_response, build_api_key_leaderboard_items,
-    build_model_leaderboard_items, build_user_leaderboard_items, compare_leaderboard_items,
-    load_user_leaderboard_metadata, AdminStatsLeaderboardNameMode,
+    build_admin_stats_leaderboard_response, build_api_key_leaderboard_items_from_summaries,
+    build_model_leaderboard_items_from_summaries, build_user_leaderboard_items_from_summaries,
+    compare_leaderboard_items, load_user_leaderboard_metadata, AdminStatsLeaderboardNameMode,
 };
 use super::range::{parse_bounded_u32, parse_nonnegative_usize};
+use super::resolve_admin_usage_time_range;
 use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
 use crate::handlers::admin::shared::{query_param_bool, query_param_value};
 use crate::GatewayError;
 use aether_admin::observability::stats::{
     admin_stats_bad_request_response, admin_stats_leaderboard_empty_response,
-    AdminStatsLeaderboardMetric, AdminStatsSortOrder, AdminStatsTimeRange, AdminStatsUsageFilter,
+    AdminStatsLeaderboardMetric, AdminStatsSortOrder, AdminStatsUsageFilter,
 };
+use aether_data_contracts::repository::usage::{UsageLeaderboardGroupBy, UsageLeaderboardQuery};
 use axum::{body::Body, http, response::Response};
 
 pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
@@ -29,7 +31,7 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
             "/api/admin/stats/leaderboard/models" | "/api/admin/stats/leaderboard/models/"
         )
     {
-        let time_range = match AdminStatsTimeRange::resolve_optional(query) {
+        let time_range = match resolve_admin_usage_time_range(query) {
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
         };
@@ -60,19 +62,33 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
         if !state.has_usage_data_reader() {
             return Ok(Some(admin_stats_leaderboard_empty_response(
                 metric,
-                time_range.as_ref(),
+                Some(&time_range),
             )));
         }
         let filters = AdminStatsUsageFilter::from_query(query);
-        let usage = state
-            .list_admin_usage_for_optional_range(time_range.as_ref(), &filters)
+        let Some((created_from_unix_secs, created_until_unix_secs)) = time_range.to_unix_bounds()
+        else {
+            return Ok(Some(admin_stats_leaderboard_empty_response(
+                metric,
+                Some(&time_range),
+            )));
+        };
+        let summaries = state
+            .summarize_usage_leaderboard(&UsageLeaderboardQuery {
+                created_from_unix_secs,
+                created_until_unix_secs,
+                group_by: UsageLeaderboardGroupBy::Model,
+                user_id: filters.user_id,
+                provider_name: filters.provider_name,
+                model: filters.model,
+            })
             .await?;
-        let mut leaderboard = build_model_leaderboard_items(&usage);
+        let mut leaderboard = build_model_leaderboard_items_from_summaries(&summaries);
         leaderboard.sort_by(|left, right| compare_leaderboard_items(metric, order, left, right));
 
         return Ok(Some(build_admin_stats_leaderboard_response(
             metric,
-            time_range.as_ref(),
+            Some(&time_range),
             &leaderboard,
             offset,
             limit,
@@ -90,7 +106,7 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
             "/api/admin/stats/leaderboard/api-keys" | "/api/admin/stats/leaderboard/api-keys/"
         )
     {
-        let time_range = match AdminStatsTimeRange::resolve_optional(query) {
+        let time_range = match resolve_admin_usage_time_range(query) {
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
         };
@@ -121,20 +137,32 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
         if !state.has_usage_data_reader() {
             return Ok(Some(admin_stats_leaderboard_empty_response(
                 metric,
-                time_range.as_ref(),
+                Some(&time_range),
             )));
         }
         let include_inactive = query_param_bool(query, "include_inactive", false);
         let exclude_admin = query_param_bool(query, "exclude_admin", false);
         let filters = AdminStatsUsageFilter::from_query(query);
-        let usage = state
-            .list_admin_usage_for_optional_range(time_range.as_ref(), &filters)
+        let Some((created_from_unix_secs, created_until_unix_secs)) = time_range.to_unix_bounds()
+        else {
+            return Ok(Some(admin_stats_leaderboard_empty_response(
+                metric,
+                Some(&time_range),
+            )));
+        };
+        let summaries = state
+            .summarize_usage_leaderboard(&UsageLeaderboardQuery {
+                created_from_unix_secs,
+                created_until_unix_secs,
+                group_by: UsageLeaderboardGroupBy::ApiKey,
+                user_id: filters.user_id,
+                provider_name: filters.provider_name,
+                model: filters.model,
+            })
             .await?;
-        let api_key_ids: Vec<String> = usage
+        let api_key_ids: Vec<String> = summaries
             .iter()
-            .filter_map(|item| item.api_key_id.clone())
-            .collect::<std::collections::BTreeSet<_>>()
-            .into_iter()
+            .map(|item| item.group_key.clone())
             .collect();
         let snapshots = if state.has_auth_api_key_data_reader() {
             Some(
@@ -152,8 +180,8 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
         } else {
             std::collections::BTreeMap::new()
         };
-        let mut leaderboard = build_api_key_leaderboard_items(
-            &usage,
+        let mut leaderboard = build_api_key_leaderboard_items_from_summaries(
+            &summaries,
             snapshots.as_deref(),
             &api_key_names,
             include_inactive,
@@ -163,7 +191,7 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
 
         return Ok(Some(build_admin_stats_leaderboard_response(
             metric,
-            time_range.as_ref(),
+            Some(&time_range),
             &leaderboard,
             offset,
             limit,
@@ -181,7 +209,7 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
             "/api/admin/stats/leaderboard/users" | "/api/admin/stats/leaderboard/users/"
         )
     {
-        let time_range = match AdminStatsTimeRange::resolve_optional(query) {
+        let time_range = match resolve_admin_usage_time_range(query) {
             Ok(value) => value,
             Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
         };
@@ -212,26 +240,39 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
         if !state.has_usage_data_reader() {
             return Ok(Some(admin_stats_leaderboard_empty_response(
                 metric,
-                time_range.as_ref(),
+                Some(&time_range),
             )));
         }
         let include_inactive = query_param_bool(query, "include_inactive", false);
         let exclude_admin = query_param_bool(query, "exclude_admin", false);
         let filters = AdminStatsUsageFilter::from_query(query);
-        let usage = state
-            .list_admin_usage_for_optional_range(time_range.as_ref(), &filters)
+        let Some((created_from_unix_secs, created_until_unix_secs)) = time_range.to_unix_bounds()
+        else {
+            return Ok(Some(admin_stats_leaderboard_empty_response(
+                metric,
+                Some(&time_range),
+            )));
+        };
+        let summaries = state
+            .summarize_usage_leaderboard(&UsageLeaderboardQuery {
+                created_from_unix_secs,
+                created_until_unix_secs,
+                group_by: UsageLeaderboardGroupBy::User,
+                user_id: filters.user_id,
+                provider_name: filters.provider_name,
+                model: filters.model,
+            })
             .await?;
-        let user_ids: Vec<String> = usage
+        let user_ids: Vec<String> = summaries
             .iter()
-            .filter_map(|item| item.user_id.clone())
-            .collect::<std::collections::BTreeSet<_>>()
-            .into_iter()
+            .map(|item| item.group_key.clone())
             .collect();
         let user_metadata = load_user_leaderboard_metadata(state, &user_ids).await?;
-        let mut leaderboard = build_user_leaderboard_items(
-            &usage,
+        let mut leaderboard = build_user_leaderboard_items_from_summaries(
+            &summaries,
             &user_metadata,
             state.has_auth_user_data_reader(),
+            state.has_user_data_reader(),
             include_inactive,
             exclude_admin,
         );
@@ -239,7 +280,7 @@ pub(super) async fn maybe_build_local_admin_stats_leaderboard_response(
 
         return Ok(Some(build_admin_stats_leaderboard_response(
             metric,
-            time_range.as_ref(),
+            Some(&time_range),
             &leaderboard,
             offset,
             limit,

apps/aether-gateway/src/handlers/admin/observability/stats/mod.rs

@@ -10,6 +10,7 @@ mod provider_quota_routes;
 mod range;
 pub(crate) use self::range::{
     list_usage_for_optional_range, list_usage_for_range, parse_bounded_u32,
+    resolve_admin_usage_time_range,
 };
 pub(crate) use aether_admin::observability::stats::{
     admin_stats_bad_request_response, aggregate_usage_stats, round_to, AdminStatsTimeRange,

apps/aether-gateway/src/handlers/admin/observability/stats/range.rs

@@ -8,6 +8,22 @@ pub(super) use aether_admin::observability::stats::{
 use aether_admin::observability::stats::{AdminStatsTimeRange, AdminStatsUsageFilter};
 use aether_data_contracts::repository::usage::{StoredRequestUsageAudit, UsageAuditListQuery};
 
+pub(crate) fn resolve_admin_usage_time_range(
+    query: Option<&str>,
+) -> Result<AdminStatsTimeRange, String> {
+    match AdminStatsTimeRange::resolve_optional(query)? {
+        Some(time_range) => Ok(time_range),
+        None => {
+            let tz_offset_minutes = parse_tz_offset_minutes(query)?;
+            let default_days = u32::try_from(admin_usage_default_days())
+                .ok()
+                .filter(|value| *value > 0)
+                .unwrap_or(1);
+            build_time_range_from_days(default_days, tz_offset_minutes)
+        }
+    }
+}
+
 pub(crate) async fn list_usage_for_range(
     state: &AdminAppState<'_>,
     time_range: &AdminStatsTimeRange,
@@ -25,8 +41,13 @@ pub(crate) async fn list_usage_for_range(
             user_id: filters.user_id.clone(),
             provider_name: filters.provider_name.clone(),
             model: filters.model.clone(),
+            api_format: None,
             statuses: None,
+            is_stream: None,
+            error_only: false,
             limit: None,
+            offset: None,
+            newest_first: false,
         })
         .await
 }
@@ -39,17 +60,9 @@ pub(crate) async fn list_usage_for_optional_range(
     match time_range {
         Some(time_range) => list_usage_for_range(state, time_range, filters).await,
         None => {
-            state
-                .list_usage_audits(&UsageAuditListQuery {
-                    created_from_unix_secs: None,
-                    created_until_unix_secs: None,
-                    user_id: filters.user_id.clone(),
-                    provider_name: filters.provider_name.clone(),
-                    model: filters.model.clone(),
-                    statuses: None,
-                    limit: None,
-                })
-                .await
+            let default_time_range = build_time_range_from_days(1, 0)
+                .map_err(|detail| GatewayError::Internal(detail.to_string()))?;
+            list_usage_for_range(state, &default_time_range, filters).await
         }
     }
 }

apps/aether-gateway/src/handlers/admin/observability/usage/analytics/aggregations.rs

@@ -1,29 +1,21 @@
 use crate::handlers::admin::request::AdminAppState;
 use crate::GatewayError;
 use aether_admin::observability::stats::round_to;
-use aether_data_contracts::repository::usage::{StoredRequestUsageAudit, UsageAuditListQuery};
+use aether_data_contracts::repository::usage::StoredUsageAuditAggregation;
 use serde_json::json;
 use std::collections::BTreeMap;
 
 pub(in super::super) async fn admin_usage_aggregation_by_user_json(
     state: &AdminAppState<'_>,
-    usage: &[StoredRequestUsageAudit],
-    limit: usize,
+    rows: &[StoredUsageAuditAggregation],
 ) -> Result<serde_json::Value, GatewayError> {
-    let mut grouped: BTreeMap<String, (u64, u64, f64)> = BTreeMap::new();
-    for item in usage {
-        let Some(user_id) = item.user_id.as_ref() else {
-            continue;
-        };
-        let entry = grouped.entry(user_id.clone()).or_insert((0, 0, 0.0));
-        entry.0 = entry.0.saturating_add(1);
-        entry.1 = entry.1.saturating_add(item.total_tokens);
-        entry.2 += item.total_cost_usd;
-    }
-
-    let usernames = if state.has_user_data_reader() && !grouped.is_empty() {
+    let user_ids = rows
+        .iter()
+        .map(|row| row.group_key.clone())
+        .collect::<Vec<_>>();
+    let usernames = if state.has_user_data_reader() && !user_ids.is_empty() {
         state
-            .list_users_by_ids(&grouped.keys().cloned().collect::<Vec<_>>())
+            .list_users_by_ids(&user_ids)
             .await?
             .into_iter()
             .map(|user| (user.id, (user.email, user.username)))
@@ -32,35 +24,25 @@ pub(in super::super) async fn admin_usage_aggregation_by_user_json(
         BTreeMap::new()
     };
 
-    let mut items: Vec<serde_json::Value> = grouped
-        .into_iter()
-        .map(|(user_id, (request_count, total_tokens, total_cost))| {
+    Ok(json!(rows
+        .iter()
+        .map(|row| {
             let (email, username) = usernames
-                .get(&user_id)
+                .get(&row.group_key)
                 .cloned()
                 .unwrap_or((None, String::new()));
             json!({
-                "user_id": user_id,
+                "user_id": row.group_key,
                 "email": email,
-                "username": if username.is_empty() { serde_json::Value::Null } else { json!(username) },
-                "request_count": request_count,
-                "total_tokens": total_tokens,
-                "total_cost": round_to(total_cost, 6),
+                "username": if username.is_empty() {
+                    serde_json::Value::Null
+                } else {
+                    json!(username)
+                },
+                "request_count": row.request_count,
+                "total_tokens": row.total_tokens,
+                "total_cost": round_to(row.total_cost_usd, 6),
             })
         })
-        .collect();
-    items.sort_by(|left, right| {
-        right["request_count"]
-            .as_u64()
-            .unwrap_or_default()
-            .cmp(&left["request_count"].as_u64().unwrap_or_default())
-            .then_with(|| {
-                left["user_id"]
-                    .as_str()
-                    .unwrap_or_default()
-                    .cmp(right["user_id"].as_str().unwrap_or_default())
-            })
-    });
-    items.truncate(limit);
-    Ok(json!(items))
+        .collect::<Vec<_>>()))
 }

apps/aether-gateway/src/handlers/admin/observability/usage/analytics/cache_affinity.rs

@@ -16,8 +16,13 @@ pub(in super::super) async fn list_recent_completed_usage_for_cache_affinity(
             user_id: user_id.map(ToOwned::to_owned),
             provider_name: None,
             model: None,
+            api_format: None,
             statuses: None,
+            is_stream: None,
+            error_only: false,
             limit: None,
+            offset: None,
+            newest_first: false,
         })
         .await?;
     items.retain(|item| item.status == "completed");

apps/aether-gateway/src/handlers/admin/observability/usage/analytics_routes/aggregation.rs

@@ -1,14 +1,17 @@
-use super::super::super::stats::{AdminStatsTimeRange, AdminStatsUsageFilter};
+use super::super::super::stats::resolve_admin_usage_time_range;
 use super::super::analytics::admin_usage_aggregation_by_user_json;
 use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
 use crate::handlers::admin::shared::query_param_value;
 use crate::GatewayError;
+use aether_admin::observability::stats::round_to;
 use aether_admin::observability::usage::{
-    admin_usage_aggregation_by_api_format_json, admin_usage_aggregation_by_model_json,
-    admin_usage_aggregation_by_provider_json, admin_usage_bad_request_response,
-    admin_usage_data_unavailable_response, admin_usage_parse_aggregation_limit,
+    admin_usage_bad_request_response, admin_usage_data_unavailable_response,
+    admin_usage_parse_aggregation_limit, admin_usage_token_cache_hit_rate,
     ADMIN_USAGE_DATA_UNAVAILABLE_DETAIL,
 };
+use aether_data_contracts::repository::usage::{
+    StoredUsageAuditAggregation, UsageAuditAggregationGroupBy, UsageAuditAggregationQuery,
+};
 use axum::{
     body::Body,
     response::{IntoResponse, Response},
@@ -16,6 +19,102 @@ use axum::{
 };
 use serde_json::json;
 
+fn admin_usage_aggregation_by_model_json(
+    rows: &[StoredUsageAuditAggregation],
+) -> serde_json::Value {
+    json!(rows
+        .iter()
+        .map(|row| {
+            json!({
+                "model": row.group_key,
+                "request_count": row.request_count,
+                "total_tokens": row.total_tokens,
+                "effective_input_tokens": row.effective_input_tokens,
+                "total_input_context": row.total_input_context,
+                "output_tokens": row.output_tokens,
+                "total_cost": round_to(row.total_cost_usd, 6),
+                "actual_cost": round_to(row.actual_total_cost_usd, 6),
+                "cache_creation_tokens": row.cache_creation_tokens,
+                "cache_creation_ephemeral_5m_tokens": row.cache_creation_ephemeral_5m_tokens,
+                "cache_creation_ephemeral_1h_tokens": row.cache_creation_ephemeral_1h_tokens,
+                "cache_read_tokens": row.cache_read_tokens,
+                "cache_hit_rate": admin_usage_token_cache_hit_rate(
+                    row.total_input_context,
+                    row.cache_read_tokens,
+                ),
+            })
+        })
+        .collect::<Vec<_>>())
+}
+
+fn admin_usage_aggregation_by_provider_json(
+    rows: &[StoredUsageAuditAggregation],
+) -> serde_json::Value {
+    json!(rows
+        .iter()
+        .map(|row| {
+            let success_count = row.success_count.unwrap_or_default();
+            let error_count = row.request_count.saturating_sub(success_count);
+            let success_rate = if row.request_count == 0 {
+                0.0
+            } else {
+                round_to(success_count as f64 / row.request_count as f64 * 100.0, 2)
+            };
+            json!({
+                "provider_id": row.group_key,
+                "provider": row.display_name.clone().unwrap_or_else(|| "Unknown".to_string()),
+                "request_count": row.request_count,
+                "total_tokens": row.total_tokens,
+                "effective_input_tokens": row.effective_input_tokens,
+                "total_input_context": row.total_input_context,
+                "output_tokens": row.output_tokens,
+                "total_cost": round_to(row.total_cost_usd, 6),
+                "actual_cost": round_to(row.actual_total_cost_usd, 6),
+                "avg_response_time_ms": round_to(row.avg_response_time_ms.unwrap_or(0.0), 2),
+                "success_rate": success_rate,
+                "error_count": error_count,
+                "cache_creation_tokens": row.cache_creation_tokens,
+                "cache_creation_ephemeral_5m_tokens": row.cache_creation_ephemeral_5m_tokens,
+                "cache_creation_ephemeral_1h_tokens": row.cache_creation_ephemeral_1h_tokens,
+                "cache_read_tokens": row.cache_read_tokens,
+                "cache_hit_rate": admin_usage_token_cache_hit_rate(
+                    row.total_input_context,
+                    row.cache_read_tokens,
+                ),
+            })
+        })
+        .collect::<Vec<_>>())
+}
+
+fn admin_usage_aggregation_by_api_format_json(
+    rows: &[StoredUsageAuditAggregation],
+) -> serde_json::Value {
+    json!(rows
+        .iter()
+        .map(|row| {
+            json!({
+                "api_format": row.group_key,
+                "request_count": row.request_count,
+                "total_tokens": row.total_tokens,
+                "effective_input_tokens": row.effective_input_tokens,
+                "total_input_context": row.total_input_context,
+                "output_tokens": row.output_tokens,
+                "total_cost": round_to(row.total_cost_usd, 6),
+                "actual_cost": round_to(row.actual_total_cost_usd, 6),
+                "avg_response_time_ms": round_to(row.avg_response_time_ms.unwrap_or(0.0), 2),
+                "cache_creation_tokens": row.cache_creation_tokens,
+                "cache_creation_ephemeral_5m_tokens": row.cache_creation_ephemeral_5m_tokens,
+                "cache_creation_ephemeral_1h_tokens": row.cache_creation_ephemeral_1h_tokens,
+                "cache_read_tokens": row.cache_read_tokens,
+                "cache_hit_rate": admin_usage_token_cache_hit_rate(
+                    row.total_input_context,
+                    row.cache_read_tokens,
+                ),
+            })
+        })
+        .collect::<Vec<_>>())
+}
+
 pub(super) async fn build_admin_usage_aggregation_stats_response(
     state: &AdminAppState<'_>,
     request_context: &AdminRequestContext<'_>,
@@ -43,21 +142,35 @@ pub(super) async fn build_admin_usage_aggregation_stats_response(
         Ok(value) => value,
         Err(detail) => return Ok(admin_usage_bad_request_response(detail)),
     };
-    let time_range = match AdminStatsTimeRange::resolve_optional(query) {
+    let time_range = match resolve_admin_usage_time_range(query) {
         Ok(value) => value,
         Err(detail) => return Ok(admin_usage_bad_request_response(detail)),
     };
-
-    let mut usage = state
-        .list_admin_usage_for_optional_range(time_range.as_ref(), &AdminStatsUsageFilter::default())
+    let Some((created_from_unix_secs, created_until_unix_secs)) = time_range.to_unix_bounds()
+    else {
+        return Ok(Json(json!([])).into_response());
+    };
+    let group_by_query = match group_by.as_str() {
+        "model" => UsageAuditAggregationGroupBy::Model,
+        "user" => UsageAuditAggregationGroupBy::User,
+        "provider" => UsageAuditAggregationGroupBy::Provider,
+        "api_format" => UsageAuditAggregationGroupBy::ApiFormat,
+        _ => unreachable!(),
+    };
+    let usage = state
+        .aggregate_usage_audits(&UsageAuditAggregationQuery {
+            created_from_unix_secs,
+            created_until_unix_secs,
+            group_by: group_by_query,
+            limit,
+        })
         .await?;
-    usage.retain(|item| item.status != "pending" && item.status != "streaming");
 
     let response = match group_by.as_str() {
-        "model" => admin_usage_aggregation_by_model_json(&usage, limit),
-        "user" => admin_usage_aggregation_by_user_json(state, &usage, limit).await?,
-        "provider" => admin_usage_aggregation_by_provider_json(&usage, limit),
-        "api_format" => admin_usage_aggregation_by_api_format_json(&usage, limit),
+        "model" => admin_usage_aggregation_by_model_json(&usage),
+        "user" => admin_usage_aggregation_by_user_json(state, &usage).await?,
+        "provider" => admin_usage_aggregation_by_provider_json(&usage),
+        "api_format" => admin_usage_aggregation_by_api_format_json(&usage),
         _ => unreachable!(),
     };
     Ok(Json(response).into_response())

apps/aether-gateway/src/handlers/admin/observability/usage/summary_routes.rs

@@ -1,4 +1,4 @@
-use super::super::stats::{AdminStatsTimeRange, AdminStatsUsageFilter};
+use super::super::stats::resolve_admin_usage_time_range;
 use super::analytics::admin_usage_api_key_names;
 use super::analytics::admin_usage_provider_key_names;
 use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
@@ -6,16 +6,89 @@ use crate::handlers::admin::shared::query_param_value;
 use crate::GatewayError;
 use aether_admin::observability::usage::{
     admin_usage_bad_request_response, admin_usage_data_unavailable_response,
-    admin_usage_matches_api_format, admin_usage_matches_eq, admin_usage_matches_search,
-    admin_usage_matches_status, admin_usage_matches_username, admin_usage_parse_ids,
+    admin_usage_matches_search, admin_usage_matches_username, admin_usage_parse_ids,
     admin_usage_parse_limit, admin_usage_parse_offset, build_admin_usage_active_requests_response,
-    build_admin_usage_records_response, build_admin_usage_summary_stats_response,
+    build_admin_usage_records_response, build_admin_usage_summary_stats_response_from_summary,
     ADMIN_USAGE_DATA_UNAVAILABLE_DETAIL,
 };
-use aether_data_contracts::repository::usage::UsageAuditListQuery;
+use aether_data_contracts::repository::usage::{
+    StoredRequestUsageAudit, UsageAuditListQuery, UsageAuditSummaryQuery,
+};
 use axum::{body::Body, http, response::Response};
 use std::collections::{BTreeMap, BTreeSet};
 
+const ADMIN_USAGE_ACTIVE_LIMIT: usize = 50;
+
+async fn load_admin_usage_by_ids(
+    state: &AdminAppState<'_>,
+    requested_ids: &BTreeSet<String>,
+) -> Result<Vec<StoredRequestUsageAudit>, GatewayError> {
+    let mut items = Vec::with_capacity(requested_ids.len());
+    for usage_id in requested_ids {
+        if let Some(item) = state.find_request_usage_by_id(usage_id).await? {
+            items.push(item);
+        }
+    }
+    Ok(items)
+}
+
+fn sort_usage_newest_first(items: &mut [StoredRequestUsageAudit]) {
+    items.sort_by(|left, right| {
+        right
+            .created_at_unix_ms
+            .cmp(&left.created_at_unix_ms)
+            .then_with(|| left.id.cmp(&right.id))
+    });
+}
+
+fn apply_admin_usage_status_filter(query: &mut UsageAuditListQuery, status: Option<&str>) {
+    let Some(status) = status
+        .map(str::trim)
+        .filter(|candidate| !candidate.is_empty())
+    else {
+        return;
+    };
+
+    match status {
+        "stream" => query.is_stream = Some(true),
+        "standard" => query.is_stream = Some(false),
+        "error" | "failed" => query.error_only = true,
+        "active" => {
+            query.statuses = Some(vec!["pending".to_string(), "streaming".to_string()]);
+        }
+        "pending" | "streaming" | "completed" | "cancelled" => {
+            query.statuses = Some(vec![status.to_string()]);
+        }
+        _ => {}
+    }
+}
+
+fn build_admin_usage_records_query(
+    created_from_unix_secs: u64,
+    created_until_unix_secs: u64,
+    query: Option<&str>,
+    limit: Option<usize>,
+    offset: Option<usize>,
+) -> UsageAuditListQuery {
+    let mut list_query = UsageAuditListQuery {
+        created_from_unix_secs: Some(created_from_unix_secs),
+        created_until_unix_secs: Some(created_until_unix_secs),
+        user_id: query_param_value(query, "user_id"),
+        provider_name: query_param_value(query, "provider"),
+        model: query_param_value(query, "model"),
+        api_format: query_param_value(query, "api_format"),
+        limit,
+        offset,
+        newest_first: true,
+        ..Default::default()
+    };
+    apply_admin_usage_status_filter(
+        &mut list_query,
+        query_param_value(query, "status").as_deref(),
+    );
+    list_query
+}
+
 pub(super) async fn maybe_build_local_admin_usage_summary_response(
     state: &AdminAppState<'_>,
     request_context: &AdminRequestContext<'_>,
@@ -40,17 +113,27 @@ pub(super) async fn maybe_build_local_admin_usage_summary_response(
             }
 
             let query = request_context.request_query_string.as_deref();
-            let time_range = match AdminStatsTimeRange::resolve_optional(query) {
+            let time_range = match resolve_admin_usage_time_range(query) {
                 Ok(value) => value,
                 Err(detail) => return Ok(Some(admin_usage_bad_request_response(detail))),
             };
-            let usage = state
-                .list_admin_usage_for_optional_range(
-                    time_range.as_ref(),
-                    &AdminStatsUsageFilter::default(),
-                )
+            let Some((created_from_unix_secs, created_until_unix_secs)) =
+                time_range.to_unix_bounds()
+            else {
+                return Ok(Some(build_admin_usage_summary_stats_response_from_summary(
+                    &Default::default(),
+                )));
+            };
+            let summary = state
+                .summarize_usage_audits(&UsageAuditSummaryQuery {
+                    created_from_unix_secs,
+                    created_until_unix_secs,
+                    ..Default::default()
+                })
                 .await?;
-            return Ok(Some(build_admin_usage_summary_stats_response(&usage)));
+            return Ok(Some(build_admin_usage_summary_stats_response_from_summary(
+                &summary,
+            )));
         }
         Some("active")
             if request_context.request_method == http::Method::GET
@@ -67,30 +150,37 @@ pub(super) async fn maybe_build_local_admin_usage_summary_response(
 
             let query = request_context.request_query_string.as_deref();
             let requested_ids = admin_usage_parse_ids(query);
-            let list_query = if requested_ids.is_some() {
-                UsageAuditListQuery::default()
+            let mut items = if let Some(requested_ids) = requested_ids.as_ref() {
+                load_admin_usage_by_ids(state, requested_ids).await?
             } else {
-                UsageAuditListQuery {
-                    statuses: Some(vec!["pending".to_string(), "streaming".to_string()]),
-                    ..Default::default()
-                }
+                let time_range = match resolve_admin_usage_time_range(query) {
+                    Ok(value) => value,
+                    Err(detail) => return Ok(Some(admin_usage_bad_request_response(detail))),
                 };
-            let usage = state.list_usage_audits(&list_query).await?;
-            let mut items: Vec<_> = usage
-                .into_iter()
-                .filter(|item| match requested_ids.as_ref() {
-                    Some(ids) => ids.contains(&item.id),
-                    None => true,
+                let Some((created_from_unix_secs, created_until_unix_secs)) =
+                    time_range.to_unix_bounds()
+                else {
+                    return Ok(Some(build_admin_usage_active_requests_response(
+                        &[],
+                        &BTreeMap::new(),
+                        state.has_auth_api_key_data_reader(),
+                        &BTreeMap::new(),
+                    )));
+                };
+                state
+                    .list_usage_audits(&UsageAuditListQuery {
+                        created_from_unix_secs: Some(created_from_unix_secs),
+                        created_until_unix_secs: Some(created_until_unix_secs),
+                        statuses: Some(vec!["pending".to_string(), "streaming".to_string()]),
+                        limit: Some(ADMIN_USAGE_ACTIVE_LIMIT),
+                        newest_first: true,
+                        ..Default::default()
                     })
-                .collect();
-            items.sort_by(|left, right| {
-                right
-                    .created_at_unix_ms
-                    .cmp(&left.created_at_unix_ms)
-                    .then_with(|| left.id.cmp(&right.id))
-            });
-            if requested_ids.is_none() && items.len() > 50 {
-                items.truncate(50);
+                    .await?
+            };
+            sort_usage_newest_first(&mut items);
+            if requested_ids.is_none() && items.len() > ADMIN_USAGE_ACTIVE_LIMIT {
+                items.truncate(ADMIN_USAGE_ACTIVE_LIMIT);
             }
             let api_key_names = admin_usage_api_key_names(state, &items).await?;
             let provider_key_names = admin_usage_provider_key_names(state, &items).await?;
@@ -116,25 +206,12 @@ pub(super) async fn maybe_build_local_admin_usage_summary_response(
             }
 
             let query = request_context.request_query_string.as_deref();
-            let time_range = match AdminStatsTimeRange::resolve_optional(query) {
+            let time_range = match resolve_admin_usage_time_range(query) {
                 Ok(value) => value,
                 Err(detail) => return Ok(Some(admin_usage_bad_request_response(detail))),
             };
-            let filters = AdminStatsUsageFilter {
-                user_id: query_param_value(query, "user_id"),
-                provider_name: None,
-                model: None,
-            };
-            let mut usage = state
-                .list_admin_usage_for_optional_range(time_range.as_ref(), &filters)
-                .await?;
-
             let search = query_param_value(query, "search");
             let username_filter = query_param_value(query, "username");
-            let model_filter = query_param_value(query, "model");
-            let provider_filter = query_param_value(query, "provider");
-            let api_format_filter = query_param_value(query, "api_format");
-            let status_filter = query_param_value(query, "status");
             let limit = match admin_usage_parse_limit(query) {
                 Ok(value) => value,
                 Err(detail) => return Ok(Some(admin_usage_bad_request_response(detail))),
@@ -143,15 +220,41 @@ pub(super) async fn maybe_build_local_admin_usage_summary_response(
                 Ok(value) => value,
                 Err(detail) => return Ok(Some(admin_usage_bad_request_response(detail))),
             };
-
+            let Some((created_from_unix_secs, created_until_unix_secs)) =
+                time_range.to_unix_bounds()
+            else {
+                return Ok(Some(build_admin_usage_records_response(
+                    &[],
+                    &BTreeMap::new(),
+                    &BTreeMap::new(),
+                    state.has_auth_user_data_reader(),
+                    state.has_auth_api_key_data_reader(),
+                    &BTreeMap::new(),
+                    0,
+                    limit,
+                    offset,
+                )));
+            };
+            let base_query = build_admin_usage_records_query(
+                created_from_unix_secs,
+                created_until_unix_secs,
+                query,
+                None,
+                None,
+            );
+            let use_metadata_fallback = search.is_some() || username_filter.is_some();
+            let (usage, total) = if use_metadata_fallback {
+                let mut usage = state.list_usage_audits(&base_query).await?;
                 let user_ids: Vec<String> = usage
                     .iter()
                     .filter_map(|item| item.user_id.clone())
                     .collect::<BTreeSet<_>>()
                     .into_iter()
                     .collect();
-            let users_by_id: BTreeMap<String, aether_data::repository::users::StoredUserSummary> =
-                state.resolve_auth_user_summaries_by_ids(&user_ids).await?;
+                let users_by_id: BTreeMap<
+                    String,
+                    aether_data::repository::users::StoredUserSummary,
+                > = state.resolve_auth_user_summaries_by_ids(&user_ids).await?;
                 let api_key_names = admin_usage_api_key_names(state, &usage).await?;
 
                 usage.retain(|item| {
@@ -167,32 +270,38 @@ pub(super) async fn maybe_build_local_admin_usage_summary_response(
                         username_filter.as_deref(),
                         &users_by_id,
                         state.has_auth_user_data_reader(),
-                ) && admin_usage_matches_eq(item.model.as_str(), model_filter.as_deref())
-                    && admin_usage_matches_eq(
-                        item.provider_name.as_str(),
-                        provider_filter.as_deref(),
                     )
-                    && admin_usage_matches_api_format(item, api_format_filter.as_deref())
-                    && admin_usage_matches_status(item, status_filter.as_deref())
-            });
-            usage.sort_by(|left, right| {
-                right
-                    .created_at_unix_ms
-                    .cmp(&left.created_at_unix_ms)
-                    .then_with(|| left.id.cmp(&right.id))
                 });
+                sort_usage_newest_first(&mut usage);
                 let total = usage.len();
-
-            let provider_key_names = admin_usage_provider_key_names(state, &usage).await?;
-
                 let records = usage
                     .into_iter()
                     .skip(offset)
                     .take(limit)
                     .collect::<Vec<_>>();
+                (records, total)
+            } else {
+                let total = usize::try_from(state.count_usage_audits(&base_query).await?)
+                    .unwrap_or(usize::MAX);
+                let mut paged_query = base_query.clone();
+                paged_query.limit = Some(limit);
+                paged_query.offset = Some(offset);
+                (state.list_usage_audits(&paged_query).await?, total)
+            };
+
+            let user_ids: Vec<String> = usage
+                .iter()
+                .filter_map(|item| item.user_id.clone())
+                .collect::<BTreeSet<_>>()
+                .into_iter()
+                .collect();
+            let users_by_id: BTreeMap<String, aether_data::repository::users::StoredUserSummary> =
+                state.resolve_auth_user_summaries_by_ids(&user_ids).await?;
+            let api_key_names = admin_usage_api_key_names(state, &usage).await?;
+            let provider_key_names = admin_usage_provider_key_names(state, &usage).await?;
 
             return Ok(Some(build_admin_usage_records_response(
-                &records,
+                &usage,
                 &users_by_id,
                 &api_key_names,
                 state.has_auth_user_data_reader(),

apps/aether-gateway/src/handlers/admin/request/observability.rs

@@ -40,6 +40,51 @@ impl<'a> AdminAppState<'a> {
         self.app.list_usage_audits(query).await
     }
 
+    pub(crate) async fn count_usage_audits(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageAuditListQuery,
+    ) -> Result<u64, GatewayError> {
+        self.app.count_usage_audits(query).await
+    }
+
+    pub(crate) async fn aggregate_usage_audits(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageAuditAggregationQuery,
+    ) -> Result<
+        Vec<aether_data_contracts::repository::usage::StoredUsageAuditAggregation>,
+        GatewayError,
+    > {
+        self.app.aggregate_usage_audits(query).await
+    }
+
+    pub(crate) async fn summarize_usage_audits(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageAuditSummaryQuery,
+    ) -> Result<aether_data_contracts::repository::usage::StoredUsageAuditSummary, GatewayError>
+    {
+        self.app.summarize_usage_audits(query).await
+    }
+
+    pub(crate) async fn summarize_usage_time_series(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageTimeSeriesQuery,
+    ) -> Result<
+        Vec<aether_data_contracts::repository::usage::StoredUsageTimeSeriesBucket>,
+        GatewayError,
+    > {
+        self.app.summarize_usage_time_series(query).await
+    }
+
+    pub(crate) async fn summarize_usage_leaderboard(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageLeaderboardQuery,
+    ) -> Result<
+        Vec<aether_data_contracts::repository::usage::StoredUsageLeaderboardSummary>,
+        GatewayError,
+    > {
+        self.app.summarize_usage_leaderboard(query).await
+    }
+
     pub(crate) async fn summarize_usage_daily_heatmap(
         &self,
         query: &aether_data_contracts::repository::usage::UsageDailyHeatmapQuery,

apps/aether-gateway/src/handlers/public/support/dashboard_filters.rs

@@ -485,8 +485,13 @@ async fn dashboard_list_usage_for_range(
             user_id: user_id.map(ToOwned::to_owned),
             provider_name: None,
             model: None,
+            api_format: None,
             statuses: None,
+            is_stream: None,
+            error_only: false,
             limit: None,
+            offset: None,
+            newest_first: false,
         })
         .await
     {
@@ -1215,8 +1220,13 @@ pub(super) async fn handle_dashboard_provider_status_get(
             user_id: None,
             provider_name: None,
             model: None,
+            api_format: None,
             statuses: None,
+            is_stream: None,
+            error_only: false,
             limit: None,
+            offset: None,
+            newest_first: false,
         })
         .await
     {

apps/aether-gateway/src/handlers/public/support/user_me_usage.rs

@@ -899,8 +899,13 @@ pub(super) async fn handle_users_me_usage_active_get(
             user_id: Some(auth.user.id.clone()),
             provider_name: None,
             model: None,
+            api_format: None,
             statuses: None,
+            is_stream: None,
+            error_only: false,
             limit: None,
+            offset: None,
+            newest_first: false,
         })
         .await
     {
@@ -972,8 +977,13 @@ pub(super) async fn handle_users_me_usage_interval_timeline_get(
             user_id: Some(auth.user.id.clone()),
             provider_name: None,
             model: None,
+            api_format: None,
             statuses: None,
+            is_stream: None,
+            error_only: false,
             limit: None,
+            offset: None,
+            newest_first: false,
         })
         .await
     {

apps/aether-gateway/src/handlers/public/support/wallet/reads.rs

@@ -217,8 +217,13 @@ pub(super) async fn handle_wallet_today_cost(
             user_id: Some(auth.user.id.clone()),
             provider_name: None,
             model: None,
+            api_format: None,
             statuses: None,
+            is_stream: None,
+            error_only: false,
             limit: None,
+            offset: None,
+            newest_first: false,
         })
         .await
     {

apps/aether-gateway/src/state/runtime/usage_queries.rs

@@ -45,6 +45,56 @@ impl AppState {
             .map_err(|err| GatewayError::Internal(err.to_string()))
     }
 
+    pub(crate) async fn count_usage_audits(
+        &self,
+        query: &usage::UsageAuditListQuery,
+    ) -> Result<u64, GatewayError> {
+        self.data
+            .count_usage_audits(query)
+            .await
+            .map_err(|err| GatewayError::Internal(err.to_string()))
+    }
+
+    pub(crate) async fn aggregate_usage_audits(
+        &self,
+        query: &usage::UsageAuditAggregationQuery,
+    ) -> Result<Vec<usage::StoredUsageAuditAggregation>, GatewayError> {
+        self.data
+            .aggregate_usage_audits(query)
+            .await
+            .map_err(|err| GatewayError::Internal(err.to_string()))
+    }
+
+    pub(crate) async fn summarize_usage_audits(
+        &self,
+        query: &usage::UsageAuditSummaryQuery,
+    ) -> Result<usage::StoredUsageAuditSummary, GatewayError> {
+        self.data
+            .summarize_usage_audits(query)
+            .await
+            .map_err(|err| GatewayError::Internal(err.to_string()))
+    }
+
+    pub(crate) async fn summarize_usage_time_series(
+        &self,
+        query: &usage::UsageTimeSeriesQuery,
+    ) -> Result<Vec<usage::StoredUsageTimeSeriesBucket>, GatewayError> {
+        self.data
+            .summarize_usage_time_series(query)
+            .await
+            .map_err(|err| GatewayError::Internal(err.to_string()))
+    }
+
+    pub(crate) async fn summarize_usage_leaderboard(
+        &self,
+        query: &usage::UsageLeaderboardQuery,
+    ) -> Result<Vec<usage::StoredUsageLeaderboardSummary>, GatewayError> {
+        self.data
+            .summarize_usage_leaderboard(query)
+            .await
+            .map_err(|err| GatewayError::Internal(err.to_string()))
+    }
+
     pub(crate) async fn summarize_usage_daily_heatmap(
         &self,
         query: &UsageDailyHeatmapQuery,

apps/aether-gateway/src/tests/control/admin/stats.rs

@@ -156,6 +156,11 @@ fn sample_api_key_snapshot(
     snapshot
 }
 
+fn recent_unix_secs(minutes_ago: u64) -> i64 {
+    let now = chrono::Utc::now().timestamp();
+    now.saturating_sub((minutes_ago * 60) as i64)
+}
+
 #[derive(Debug)]
 struct PartialListAuthApiKeyRepository {
     lookup: InMemoryAuthApiKeySnapshotRepository,
@@ -673,6 +678,83 @@ async fn gateway_handles_admin_stats_error_distribution_locally_without_usage_re
     upstream_handle.abort();
 }
 
+#[tokio::test]
+async fn gateway_defaults_admin_stats_error_distribution_to_bounded_recent_window_when_query_missing(
+) {
+    let (_upstream_url, upstream_hits, upstream_handle) =
+        start_stats_upstream("/api/admin/stats/errors/distribution").await;
+
+    let mut recent_error = sample_usage_row(
+        "usage-error-recent",
+        "req-error-recent",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "OpenAI",
+        "gpt-5",
+        20,
+        10,
+        0.02,
+        0.02,
+        recent_unix_secs(5),
+    );
+    recent_error.status_code = Some(429);
+    recent_error.error_category = Some("rate_limit".to_string());
+    recent_error.error_message = Some("rate limited".to_string());
+
+    let mut stale_error = sample_usage_row(
+        "usage-error-stale",
+        "req-error-stale",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "OpenAI",
+        "gpt-5",
+        20,
+        10,
+        0.02,
+        0.02,
+        recent_unix_secs(60 * 48),
+    );
+    stale_error.status_code = Some(401);
+    stale_error.error_category = Some("auth".to_string());
+    stale_error.error_message = Some("bad key".to_string());
+
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(vec![
+        recent_error,
+        stale_error,
+    ]));
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(GatewayDataState::with_usage_reader_for_tests(
+                usage_repository,
+            )),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = admin_request(
+        reqwest::Client::new().get(format!("{gateway_url}/api/admin/stats/errors/distribution")),
+    )
+    .send()
+    .await
+    .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(
+        payload["distribution"].as_array().map(|items| items.len()),
+        Some(1)
+    );
+    assert_eq!(payload["distribution"][0]["category"], "rate_limit");
+    assert_eq!(payload["distribution"][0]["count"], 1);
+    assert_eq!(payload["trend"][0]["total"], 1);
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_handles_admin_stats_performance_percentiles_locally_with_trusted_admin_principal()
 {
@@ -839,6 +921,80 @@ async fn gateway_handles_admin_stats_time_series_locally_with_trusted_admin_prin
     upstream_handle.abort();
 }
 
+#[tokio::test]
+async fn gateway_handles_admin_stats_time_series_hourly_locally_with_model_filter() {
+    let (_upstream_url, upstream_hits, upstream_handle) =
+        start_stats_upstream("/api/admin/stats/time-series").await;
+
+    let mut matching_row = sample_usage_row(
+        "usage-ts-hour-match",
+        "req-ts-hour-match",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "OpenAI",
+        "gpt-5",
+        80,
+        20,
+        0.12,
+        0.12,
+        1_710_997_800,
+    );
+    matching_row.cache_creation_input_tokens = 4;
+    matching_row.cache_read_input_tokens = 6;
+
+    let other_model_row = sample_usage_row(
+        "usage-ts-hour-other",
+        "req-ts-hour-other",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "OpenAI",
+        "gpt-4o-mini",
+        200,
+        40,
+        0.22,
+        0.22,
+        1_710_998_400,
+    );
+
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(vec![
+        matching_row,
+        other_model_row,
+    ]));
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(GatewayDataState::with_usage_reader_for_tests(
+                usage_repository,
+            )),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = admin_request(
+        reqwest::Client::new().get(format!(
+            "{gateway_url}/api/admin/stats/time-series?start_date=2024-03-21&end_date=2024-03-21&granularity=hour&model=gpt-5&tz_offset_minutes=0"
+        )),
+    )
+    .send()
+    .await
+    .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload.as_array().map(|items| items.len()), Some(24));
+    assert_eq!(payload[5]["date"], "2024-03-21T05:00:00+00:00");
+    assert_eq!(payload[5]["total_requests"], 1);
+    assert_eq!(payload[5]["input_tokens"], 80);
+    assert_eq!(payload[5]["cache_creation_tokens"], 4);
+    assert_eq!(payload[5]["cache_read_tokens"], 6);
+    assert_eq!(payload[6]["total_requests"], 0);
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_handles_admin_stats_time_series_locally_without_usage_reader() {
     let (upstream_url, upstream_hits, upstream_handle) =
@@ -1055,6 +1211,71 @@ async fn gateway_handles_admin_stats_leaderboard_models_locally_without_usage_re
     upstream_handle.abort();
 }
 
+#[tokio::test]
+async fn gateway_defaults_admin_stats_leaderboard_models_to_bounded_recent_window_when_query_missing(
+) {
+    let (_upstream_url, upstream_hits, upstream_handle) =
+        start_stats_upstream("/api/admin/stats/leaderboard/models").await;
+
+    let recent_row = sample_usage_row(
+        "usage-model-recent",
+        "req-model-recent",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "OpenAI",
+        "gpt-5",
+        100,
+        50,
+        0.4,
+        0.4,
+        recent_unix_secs(10),
+    );
+    let stale_row = sample_usage_row(
+        "usage-model-stale",
+        "req-model-stale",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "Anthropic",
+        "claude-3-5-sonnet",
+        60,
+        20,
+        0.2,
+        0.2,
+        recent_unix_secs(60 * 48),
+    );
+
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(vec![
+        recent_row, stale_row,
+    ]));
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(GatewayDataState::with_usage_reader_for_tests(
+                usage_repository,
+            )),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = admin_request(reqwest::Client::new().get(format!(
+        "{gateway_url}/api/admin/stats/leaderboard/models?metric=tokens&order=desc"
+    )))
+    .send()
+    .await
+    .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["total"], 1);
+    assert_eq!(payload["items"][0]["id"], "gpt-5");
+    assert_eq!(payload["items"][0]["value"], 150);
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_handles_admin_stats_leaderboard_api_keys_locally_with_trusted_admin_principal() {
     let (upstream_url, upstream_hits, upstream_handle) =

apps/aether-gateway/src/tests/control/admin/usage.rs

@@ -346,6 +346,72 @@ async fn gateway_handles_admin_usage_stats_locally_with_trusted_admin_principal(
     upstream_handle.abort();
 }
 
+#[tokio::test]
+async fn gateway_defaults_admin_usage_stats_to_bounded_recent_window_when_query_missing() {
+    let (upstream_url, upstream_hits, upstream_handle) =
+        start_usage_upstream("/api/admin/usage/stats").await;
+
+    let recent_created_at = recent_unix_secs(5);
+    let stale_created_at = recent_unix_secs(60 * 48);
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(vec![
+        sample_usage_row(
+            "usage-recent",
+            "req-recent",
+            Some("user-1"),
+            Some("key-1"),
+            Some("primary"),
+            "OpenAI",
+            "gpt-5",
+            "completed",
+            120,
+            30,
+            0.3,
+            0.36,
+            recent_created_at,
+        ),
+        sample_usage_row(
+            "usage-stale",
+            "req-stale",
+            Some("user-2"),
+            Some("key-2"),
+            Some("secondary"),
+            "Anthropic",
+            "claude-3-7",
+            "failed",
+            40,
+            10,
+            0.1,
+            0.12,
+            stale_created_at,
+        ),
+    ]));
+
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(GatewayDataState::with_usage_reader_for_tests(
+                usage_repository,
+            )),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response =
+        admin_request(reqwest::Client::new().get(format!("{gateway_url}/api/admin/usage/stats")))
+            .send()
+            .await
+            .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["total_requests"], 1);
+    assert_eq!(payload["total_tokens"], 170);
+    assert_eq!(payload["error_count"], 0);
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_returns_service_unavailable_for_admin_usage_stats_without_usage_reader() {
     assert_admin_usage_route_returns_local_503(
@@ -435,7 +501,7 @@ async fn gateway_handles_admin_usage_aggregation_stats_locally_with_trusted_admi
     let (gateway_url, gateway_handle) = start_server(gateway).await;
 
     let response = admin_request(reqwest::Client::new().get(format!(
-        "{gateway_url}/api/admin/usage/aggregation/stats?group_by=model&limit=10"
+        "{gateway_url}/api/admin/usage/aggregation/stats?group_by=model&limit=10&start_date=2024-03-21&end_date=2024-03-22&tz_offset_minutes=0"
     )))
     .send()
     .await
@@ -458,7 +524,7 @@ async fn gateway_handles_admin_usage_aggregation_stats_locally_with_trusted_admi
     assert_eq!(items[1]["output_tokens"], 20);
 
     let provider_response = admin_request(reqwest::Client::new().get(format!(
-        "{gateway_url}/api/admin/usage/aggregation/stats?group_by=provider&limit=10"
+        "{gateway_url}/api/admin/usage/aggregation/stats?group_by=provider&limit=10&start_date=2024-03-21&end_date=2024-03-22&tz_offset_minutes=0"
     )))
     .send()
     .await
@@ -477,7 +543,7 @@ async fn gateway_handles_admin_usage_aggregation_stats_locally_with_trusted_admi
     assert_eq!(provider_items[1]["output_tokens"], 20);
 
     let api_format_response = admin_request(reqwest::Client::new().get(format!(
-        "{gateway_url}/api/admin/usage/aggregation/stats?group_by=api_format&limit=10"
+        "{gateway_url}/api/admin/usage/aggregation/stats?group_by=api_format&limit=10&start_date=2024-03-21&end_date=2024-03-22&tz_offset_minutes=0"
     )))
     .send()
     .await
@@ -578,7 +644,7 @@ async fn gateway_handles_admin_usage_aggregation_stats_locally_with_bearer_admin
 
     let response = reqwest::Client::new()
         .get(format!(
-            "{gateway_url}/api/admin/usage/aggregation/stats?group_by=user"
+            "{gateway_url}/api/admin/usage/aggregation/stats?group_by=user&start_date=2024-03-21&end_date=2024-03-22&tz_offset_minutes=0"
         ))
         .header("authorization", format!("Bearer {access_token}"))
         .header("x-client-device-id", "device-admin-usage")
@@ -739,7 +805,9 @@ async fn gateway_handles_admin_usage_active_locally_with_trusted_admin_principal
     let (gateway_url, gateway_handle) = start_server(gateway).await;
 
     let response =
-        admin_request(reqwest::Client::new().get(format!("{gateway_url}/api/admin/usage/active")))
+        admin_request(reqwest::Client::new().get(format!(
+            "{gateway_url}/api/admin/usage/active?start_date=2024-03-21&end_date=2024-03-22&tz_offset_minutes=0"
+        )))
         .send()
         .await
         .expect("request should succeed");
@@ -761,6 +829,136 @@ async fn gateway_handles_admin_usage_active_locally_with_trusted_admin_principal
     upstream_handle.abort();
 }
 
+#[tokio::test]
+async fn gateway_defaults_admin_usage_active_to_recent_window_when_query_missing() {
+    let (upstream_url, upstream_hits, upstream_handle) =
+        start_usage_upstream("/api/admin/usage/active").await;
+
+    let recent_created_at = recent_unix_secs(3);
+    let stale_created_at = recent_unix_secs(60 * 48);
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(vec![
+        sample_usage_row(
+            "usage-recent-pending",
+            "req-recent-pending",
+            Some("user-1"),
+            Some("key-1"),
+            Some("primary"),
+            "OpenAI",
+            "gpt-5",
+            "pending",
+            10,
+            0,
+            0.0,
+            0.0,
+            recent_created_at,
+        ),
+        sample_usage_row(
+            "usage-stale-pending",
+            "req-stale-pending",
+            Some("user-2"),
+            Some("key-2"),
+            Some("secondary"),
+            "Anthropic",
+            "claude-3-7",
+            "pending",
+            40,
+            10,
+            0.1,
+            0.12,
+            stale_created_at,
+        ),
+        sample_usage_row(
+            "usage-recent-completed",
+            "req-recent-completed",
+            Some("user-3"),
+            Some("key-3"),
+            Some("tertiary"),
+            "Google",
+            "gemini-2.5-pro",
+            "completed",
+            20,
+            5,
+            0.2,
+            0.22,
+            recent_created_at + 1,
+        ),
+    ]));
+
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(GatewayDataState::with_usage_reader_for_tests(
+                usage_repository,
+            )),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response =
+        admin_request(reqwest::Client::new().get(format!("{gateway_url}/api/admin/usage/active")))
+            .send()
+            .await
+            .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    let requests = payload["requests"].as_array().expect("array");
+    assert_eq!(requests.len(), 1);
+    assert_eq!(requests[0]["id"], "usage-recent-pending");
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
+#[tokio::test]
+async fn gateway_handles_admin_usage_active_ids_for_terminal_updates() {
+    let (upstream_url, upstream_hits, upstream_handle) =
+        start_usage_upstream("/api/admin/usage/active").await;
+
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(vec![sample_usage_row(
+        "usage-completed",
+        "req-completed",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "OpenAI",
+        "gpt-5",
+        "completed",
+        20,
+        5,
+        0.2,
+        0.24,
+        recent_unix_secs(2),
+    )]));
+
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(GatewayDataState::with_usage_reader_for_tests(
+                usage_repository,
+            )),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = admin_request(reqwest::Client::new().get(format!(
+        "{gateway_url}/api/admin/usage/active?ids=usage-completed"
+    )))
+    .send()
+    .await
+    .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    let requests = payload["requests"].as_array().expect("array");
+    assert_eq!(requests.len(), 1);
+    assert_eq!(requests[0]["id"], "usage-completed");
+    assert_eq!(requests[0]["status"], "completed");
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_handles_admin_usage_records_locally_with_trusted_admin_principal() {
     let (upstream_url, upstream_hits, upstream_handle) =
@@ -825,7 +1023,7 @@ async fn gateway_handles_admin_usage_records_locally_with_trusted_admin_principa
     let (gateway_url, gateway_handle) = start_server(gateway).await;
 
     let response = admin_request(reqwest::Client::new().get(format!(
-        "{gateway_url}/api/admin/usage/records?status=failed&provider=Anthropic&limit=10&offset=0"
+        "{gateway_url}/api/admin/usage/records?start_date=2024-03-21&end_date=2024-03-22&tz_offset_minutes=0&status=failed&provider=Anthropic&limit=10&offset=0"
     )))
     .send()
     .await
@@ -949,7 +1147,7 @@ async fn gateway_handles_admin_usage_records_with_snapshot_first_user_and_api_ke
     let (gateway_url, gateway_handle) = start_server(gateway).await;
 
     let response = admin_request(reqwest::Client::new().get(format!(
-        "{gateway_url}/api/admin/usage/records?search=fresh-secondary&username=fresh-bob&limit=10&offset=0"
+        "{gateway_url}/api/admin/usage/records?start_date=2024-03-21&end_date=2024-03-22&tz_offset_minutes=0&search=fresh-secondary&username=fresh-bob&limit=10&offset=0"
     )))
     .send()
     .await

crates/aether-admin/src/observability/stats.rs

@@ -1,6 +1,7 @@
 use aether_data::repository::auth::StoredAuthApiKeySnapshot;
 use aether_data_contracts::repository::{
-    provider_catalog::StoredProviderCatalogProvider, usage::StoredRequestUsageAudit,
+    provider_catalog::StoredProviderCatalogProvider,
+    usage::{StoredRequestUsageAudit, StoredUsageLeaderboardSummary, StoredUsageTimeSeriesBucket},
 };
 use axum::{
     body::Body,
@@ -811,7 +812,20 @@ pub fn build_admin_stats_comparison_response(
 ) -> Response<Body> {
     let current = aggregate_usage_stats(current_usage);
     let comparison = aggregate_usage_stats(comparison_usage);
+    build_admin_stats_comparison_response_from_aggregates(
+        &current,
+        &comparison,
+        current_range,
+        comparison_range,
+    )
+}
 
+pub fn build_admin_stats_comparison_response_from_aggregates(
+    current: &AdminStatsAggregate,
+    comparison: &AdminStatsAggregate,
+    current_range: &AdminStatsTimeRange,
+    comparison_range: &AdminStatsTimeRange,
+) -> Response<Body> {
     Json(json!({
         "current": {
             "total_requests": current.total_requests,
@@ -973,6 +987,171 @@ pub fn build_admin_stats_time_series_response(
     .into_response()
 }
 
+fn admin_stats_time_series_bucket_from_summary(
+    bucket: &StoredUsageTimeSeriesBucket,
+) -> AdminStatsTimeSeriesBucket {
+    AdminStatsTimeSeriesBucket {
+        total_requests: bucket.total_requests,
+        input_tokens: bucket.input_tokens,
+        output_tokens: bucket.output_tokens,
+        cache_creation_tokens: bucket.cache_creation_tokens,
+        cache_read_tokens: bucket.cache_read_tokens,
+        total_cost: bucket.total_cost_usd,
+        total_response_time_ms: bucket.total_response_time_ms,
+    }
+}
+
+fn build_daily_time_series_buckets_from_summaries(
+    time_range: &AdminStatsTimeRange,
+    buckets: &[StoredUsageTimeSeriesBucket],
+) -> std::collections::BTreeMap<chrono::NaiveDate, AdminStatsTimeSeriesBucket> {
+    let mut values: std::collections::BTreeMap<chrono::NaiveDate, AdminStatsTimeSeriesBucket> =
+        time_range
+            .local_dates()
+            .into_iter()
+            .map(|date| (date, AdminStatsTimeSeriesBucket::default()))
+            .collect();
+
+    for bucket in buckets {
+        let Ok(date) = chrono::NaiveDate::parse_from_str(&bucket.bucket_key, "%Y-%m-%d") else {
+            continue;
+        };
+        let Some(value) = values.get_mut(&date) else {
+            continue;
+        };
+        value.merge(&admin_stats_time_series_bucket_from_summary(bucket));
+    }
+
+    values
+}
+
+fn build_daily_time_series_payload_from_summaries(
+    time_range: &AdminStatsTimeRange,
+    buckets: &[StoredUsageTimeSeriesBucket],
+) -> Vec<serde_json::Value> {
+    build_daily_time_series_buckets_from_summaries(time_range, buckets)
+        .into_iter()
+        .map(|(date, bucket)| bucket.to_json_with_avg(date.to_string()))
+        .collect()
+}
+
+fn build_weekly_time_series_payload_from_summaries(
+    time_range: &AdminStatsTimeRange,
+    buckets: &[StoredUsageTimeSeriesBucket],
+) -> Vec<serde_json::Value> {
+    let mut weekly: std::collections::BTreeMap<
+        (i32, u32),
+        (chrono::NaiveDate, AdminStatsTimeSeriesBucket),
+    > = std::collections::BTreeMap::new();
+
+    for (date, bucket) in build_daily_time_series_buckets_from_summaries(time_range, buckets) {
+        let iso = date.iso_week();
+        let entry = weekly
+            .entry((iso.year(), iso.week()))
+            .or_insert_with(|| (date, AdminStatsTimeSeriesBucket::default()));
+        entry.0 = entry.0.min(date);
+        entry.1.merge(&bucket);
+    }
+
+    weekly
+        .into_values()
+        .map(|(date, bucket)| bucket.to_json_with_avg(date.to_string()))
+        .collect()
+}
+
+fn build_monthly_time_series_payload_from_summaries(
+    time_range: &AdminStatsTimeRange,
+    buckets: &[StoredUsageTimeSeriesBucket],
+) -> Vec<serde_json::Value> {
+    let mut monthly: std::collections::BTreeMap<
+        (i32, u32),
+        (chrono::NaiveDate, AdminStatsTimeSeriesBucket),
+    > = std::collections::BTreeMap::new();
+
+    for (date, bucket) in build_daily_time_series_buckets_from_summaries(time_range, buckets) {
+        let Some(month_start) = chrono::NaiveDate::from_ymd_opt(date.year(), date.month(), 1)
+        else {
+            continue;
+        };
+        let entry = monthly
+            .entry((date.year(), date.month()))
+            .or_insert_with(|| (month_start, AdminStatsTimeSeriesBucket::default()));
+        entry.1.merge(&bucket);
+    }
+
+    monthly
+        .into_values()
+        .map(|(date, bucket)| bucket.to_json_with_avg(date.to_string()))
+        .collect()
+}
+
+fn build_hourly_time_series_payload_from_summaries(
+    time_range: &AdminStatsTimeRange,
+    buckets: &[StoredUsageTimeSeriesBucket],
+) -> Vec<serde_json::Value> {
+    let Some((mut current, end)) = time_range.to_utc_datetime_bounds() else {
+        return Vec::new();
+    };
+    let offset = chrono::Duration::minutes(i64::from(time_range.tz_offset_minutes));
+    let mut values: std::collections::BTreeMap<String, AdminStatsTimeSeriesBucket> =
+        std::collections::BTreeMap::new();
+
+    while current < end {
+        let label = (current + offset)
+            .format("%Y-%m-%dT%H:00:00+00:00")
+            .to_string();
+        values.insert(label, AdminStatsTimeSeriesBucket::default());
+        let Some(next) = current.checked_add_signed(chrono::Duration::hours(1)) else {
+            break;
+        };
+        current = next;
+    }
+
+    for bucket in buckets {
+        let Some(value) = values.get_mut(&bucket.bucket_key) else {
+            continue;
+        };
+        value.merge(&admin_stats_time_series_bucket_from_summary(bucket));
+    }
+
+    values
+        .into_iter()
+        .map(|(date, bucket)| bucket.to_json_without_avg(date))
+        .collect()
+}
+
+pub fn build_time_series_payload_from_summaries(
+    time_range: &AdminStatsTimeRange,
+    granularity: AdminStatsGranularity,
+    buckets: &[StoredUsageTimeSeriesBucket],
+) -> Vec<serde_json::Value> {
+    match granularity {
+        AdminStatsGranularity::Hour => {
+            build_hourly_time_series_payload_from_summaries(time_range, buckets)
+        }
+        AdminStatsGranularity::Day => {
+            build_daily_time_series_payload_from_summaries(time_range, buckets)
+        }
+        AdminStatsGranularity::Week => {
+            build_weekly_time_series_payload_from_summaries(time_range, buckets)
+        }
+        AdminStatsGranularity::Month => {
+            build_monthly_time_series_payload_from_summaries(time_range, buckets)
+        }
+    }
+}
+
+pub fn build_admin_stats_time_series_response_from_summaries(
+    time_range: &AdminStatsTimeRange,
+    granularity: AdminStatsGranularity,
+    buckets: &[StoredUsageTimeSeriesBucket],
+) -> Response<Body> {
+    Json(serde_json::Value::Array(
+        build_time_series_payload_from_summaries(time_range, granularity, buckets),
+    ))
+    .into_response()
+}
+
 pub fn build_admin_stats_cost_forecast_response(
     time_range: &AdminStatsTimeRange,
     forecast_days: u32,
@@ -1293,6 +1472,21 @@ pub fn build_model_leaderboard_items(
     grouped.into_values().collect()
 }
 
+pub fn build_model_leaderboard_items_from_summaries(
+    items: &[StoredUsageLeaderboardSummary],
+) -> Vec<AdminStatsLeaderboardItem> {
+    items
+        .iter()
+        .map(|item| AdminStatsLeaderboardItem {
+            id: item.group_key.clone(),
+            name: item.group_key.clone(),
+            requests: item.request_count,
+            tokens: item.total_tokens,
+            cost: item.total_cost_usd,
+        })
+        .collect()
+}
+
 pub fn build_user_leaderboard_items(
     items: &[StoredRequestUsageAudit],
     users: &std::collections::BTreeMap<String, AdminStatsUserMetadata>,
@@ -1362,6 +1556,57 @@ pub fn build_user_leaderboard_items(
     grouped.into_values().collect()
 }
 
+pub fn build_user_leaderboard_items_from_summaries(
+    items: &[StoredUsageLeaderboardSummary],
+    users: &std::collections::BTreeMap<String, AdminStatsUserMetadata>,
+    auth_user_reader_available: bool,
+    user_reader_available: bool,
+    include_inactive: bool,
+    exclude_admin: bool,
+) -> Vec<AdminStatsLeaderboardItem> {
+    let mut grouped = Vec::new();
+
+    for item in items {
+        let user_id = item.group_key.as_str();
+        let entry_name = if let Some(user) = users.get(user_id) {
+            if user.is_deleted {
+                continue;
+            }
+            if !include_inactive && !user.is_active {
+                continue;
+            }
+            if exclude_admin && user.role.eq_ignore_ascii_case("admin") {
+                continue;
+            }
+            user.name.clone()
+        } else {
+            if exclude_admin {
+                continue;
+            }
+            if auth_user_reader_available || user_reader_available {
+                user_id.to_string()
+            } else {
+                item.legacy_name
+                    .as_deref()
+                    .map(str::trim)
+                    .filter(|value| !value.is_empty())
+                    .map(ToOwned::to_owned)
+                    .unwrap_or_else(|| user_id.to_string())
+            }
+        };
+
+        grouped.push(AdminStatsLeaderboardItem {
+            id: user_id.to_string(),
+            name: entry_name,
+            requests: item.request_count,
+            tokens: item.total_tokens,
+            cost: item.total_cost_usd,
+        });
+    }
+
+    grouped
+}
+
 pub fn build_api_key_leaderboard_items(
     items: &[StoredRequestUsageAudit],
     snapshots: Option<&[StoredAuthApiKeySnapshot]>,
@@ -1436,6 +1681,60 @@ pub fn build_api_key_leaderboard_items(
     grouped.into_values().collect()
 }
 
+pub fn build_api_key_leaderboard_items_from_summaries(
+    items: &[StoredUsageLeaderboardSummary],
+    snapshots: Option<&[StoredAuthApiKeySnapshot]>,
+    api_key_names: &std::collections::BTreeMap<String, String>,
+    include_inactive: bool,
+    exclude_admin: bool,
+) -> Vec<AdminStatsLeaderboardItem> {
+    let snapshot_by_api_key_id: std::collections::BTreeMap<_, _> = snapshots
+        .unwrap_or(&[])
+        .iter()
+        .map(|snapshot| (snapshot.api_key_id.as_str(), snapshot))
+        .collect();
+    let snapshots_available = snapshots.is_some();
+    let mut grouped = Vec::new();
+
+    for item in items {
+        let api_key_id = item.group_key.as_str();
+        let entry_name = if let Some(snapshot) = snapshot_by_api_key_id.get(api_key_id) {
+            if snapshot.user_is_deleted {
+                continue;
+            }
+            if !include_inactive && !snapshot.api_key_is_active {
+                continue;
+            }
+            if exclude_admin && snapshot.user_role.eq_ignore_ascii_case("admin") {
+                continue;
+            }
+            api_key_names
+                .get(api_key_id)
+                .cloned()
+                .unwrap_or_else(|| api_key_id.to_string())
+        } else {
+            if snapshots_available {
+                continue;
+            }
+            api_key_names
+                .get(api_key_id)
+                .cloned()
+                .or_else(|| item.legacy_name.clone())
+                .unwrap_or_else(|| api_key_id.to_string())
+        };
+
+        grouped.push(AdminStatsLeaderboardItem {
+            id: api_key_id.to_string(),
+            name: entry_name,
+            requests: item.request_count,
+            tokens: item.total_tokens,
+            cost: item.total_cost_usd,
+        });
+    }
+
+    grouped
+}
+
 pub fn compare_leaderboard_items(
     metric: AdminStatsLeaderboardMetric,
     order: AdminStatsSortOrder,

crates/aether-admin/src/observability/usage.rs

@@ -5,7 +5,7 @@ use aether_billing::{
 use aether_data::repository::users::StoredUserSummary;
 use aether_data_contracts::repository::{
     provider_catalog::{StoredProviderCatalogEndpoint, StoredProviderCatalogProvider},
-    usage::{StoredRequestUsageAudit, UsageBodyField},
+    usage::{StoredRequestUsageAudit, StoredUsageAuditSummary, UsageBodyField},
 };
 use axum::{
     body::Body,
@@ -1426,53 +1426,83 @@ pub fn admin_usage_build_curl_command(
     parts.join(" \\\n  ")
 }
 
-pub fn build_admin_usage_summary_stats_response(
-    usage: &[StoredRequestUsageAudit],
-) -> Response<Body> {
+fn summarize_admin_usage_stats(usage: &[StoredRequestUsageAudit]) -> StoredUsageAuditSummary {
     let aggregate = aggregate_usage_stats(usage);
-    let cache_creation_tokens: u64 = usage.iter().map(admin_usage_cache_creation_tokens).sum();
-    let cache_creation_ephemeral_5m_tokens: u64 = usage
+    StoredUsageAuditSummary {
+        total_requests: aggregate.total_requests,
+        input_tokens: usage.iter().map(|item| item.input_tokens).sum(),
+        output_tokens: usage.iter().map(|item| item.output_tokens).sum(),
+        recorded_total_tokens: aggregate.total_tokens,
+        cache_creation_tokens: usage.iter().map(admin_usage_cache_creation_tokens).sum(),
+        cache_creation_ephemeral_5m_tokens: usage
             .iter()
             .map(|item| item.cache_creation_ephemeral_5m_input_tokens)
-        .sum();
-    let cache_creation_ephemeral_1h_tokens: u64 = usage
+            .sum(),
+        cache_creation_ephemeral_1h_tokens: usage
             .iter()
             .map(|item| item.cache_creation_ephemeral_1h_input_tokens)
-        .sum();
-    let cache_read_tokens: u64 = usage.iter().map(|item| item.cache_read_input_tokens).sum();
-    let cache_creation_cost: f64 = usage.iter().map(|item| item.cache_creation_cost_usd).sum();
-    let cache_read_cost: f64 = usage.iter().map(|item| item.cache_read_cost_usd).sum();
-    let total_tokens: u64 = usage.iter().map(admin_usage_total_tokens).sum();
-    let avg_response_time = round_to(aggregate.avg_response_time_ms() / 1000.0, 2);
-    let error_rate = if aggregate.total_requests == 0 {
+            .sum(),
+        cache_read_tokens: usage.iter().map(|item| item.cache_read_input_tokens).sum(),
+        total_cost_usd: aggregate.total_cost,
+        actual_total_cost_usd: aggregate.actual_total_cost,
+        cache_creation_cost_usd: usage.iter().map(|item| item.cache_creation_cost_usd).sum(),
+        cache_read_cost_usd: usage.iter().map(|item| item.cache_read_cost_usd).sum(),
+        total_response_time_ms: aggregate.total_response_time_ms,
+        error_requests: aggregate.error_requests,
+    }
+}
+
+pub fn build_admin_usage_summary_stats_response_from_summary(
+    summary: &StoredUsageAuditSummary,
+) -> Response<Body> {
+    let total_tokens = summary
+        .input_tokens
+        .saturating_add(summary.output_tokens)
+        .saturating_add(summary.cache_creation_tokens)
+        .saturating_add(summary.cache_read_tokens);
+    let avg_response_time = if summary.total_requests == 0 {
         0.0
     } else {
         round_to(
-            (aggregate.error_requests as f64 / aggregate.total_requests as f64) * 100.0,
+            summary.total_response_time_ms / summary.total_requests as f64 / 1000.0,
+            2,
+        )
+    };
+    let error_rate = if summary.total_requests == 0 {
+        0.0
+    } else {
+        round_to(
+            (summary.error_requests as f64 / summary.total_requests as f64) * 100.0,
             2,
         )
     };
 
     Json(json!({
-        "total_requests": aggregate.total_requests,
+        "total_requests": summary.total_requests,
         "total_tokens": total_tokens,
-        "total_cost": round_to(aggregate.total_cost, 6),
-        "total_actual_cost": round_to(aggregate.actual_total_cost, 6),
+        "total_cost": round_to(summary.total_cost_usd, 6),
+        "total_actual_cost": round_to(summary.actual_total_cost_usd, 6),
         "avg_response_time": avg_response_time,
-        "error_count": aggregate.error_requests,
+        "error_count": summary.error_requests,
         "error_rate": error_rate,
         "cache_stats": {
-            "cache_creation_tokens": cache_creation_tokens,
-            "cache_creation_ephemeral_5m_tokens": cache_creation_ephemeral_5m_tokens,
-            "cache_creation_ephemeral_1h_tokens": cache_creation_ephemeral_1h_tokens,
-            "cache_read_tokens": cache_read_tokens,
-            "cache_creation_cost": round_to(cache_creation_cost, 6),
-            "cache_read_cost": round_to(cache_read_cost, 6),
+            "cache_creation_tokens": summary.cache_creation_tokens,
+            "cache_creation_ephemeral_5m_tokens": summary.cache_creation_ephemeral_5m_tokens,
+            "cache_creation_ephemeral_1h_tokens": summary.cache_creation_ephemeral_1h_tokens,
+            "cache_read_tokens": summary.cache_read_tokens,
+            "cache_creation_cost": round_to(summary.cache_creation_cost_usd, 6),
+            "cache_read_cost": round_to(summary.cache_read_cost_usd, 6),
         }
     }))
     .into_response()
 }
 
+pub fn build_admin_usage_summary_stats_response(
+    usage: &[StoredRequestUsageAudit],
+) -> Response<Body> {
+    build_admin_usage_summary_stats_response_from_summary(&summarize_admin_usage_stats(usage))
+}
+
 pub fn build_admin_usage_active_requests_response(
     items: &[StoredRequestUsageAudit],
     api_key_names: &BTreeMap<String, String>,

crates/aether-data-contracts/src/repository/usage/mod.rs

@@ -3,6 +3,10 @@ mod types;
 pub use types::{
     parse_usage_body_ref, usage_body_ref, StoredProviderApiKeyUsageSummary,
     StoredProviderUsageSummary, StoredProviderUsageWindow, StoredRequestUsageAudit,
-    StoredUsageDailySummary, UpsertUsageRecord, UsageAuditListQuery, UsageBodyField,
-    UsageDailyHeatmapQuery, UsageReadRepository, UsageRepository, UsageWriteRepository,
+    StoredUsageAuditAggregation, StoredUsageAuditSummary, StoredUsageDailySummary,
+    StoredUsageLeaderboardSummary, StoredUsageTimeSeriesBucket, UpsertUsageRecord,
+    UsageAuditAggregationGroupBy, UsageAuditAggregationQuery, UsageAuditListQuery,
+    UsageAuditSummaryQuery, UsageBodyField, UsageDailyHeatmapQuery, UsageLeaderboardGroupBy,
+    UsageLeaderboardQuery, UsageReadRepository, UsageRepository, UsageTimeSeriesGranularity,
+    UsageTimeSeriesQuery, UsageWriteRepository,
 };

crates/aether-data-contracts/src/repository/usage/types.rs

@@ -480,8 +480,134 @@ pub struct UsageAuditListQuery {
     pub user_id: Option<String>,
     pub provider_name: Option<String>,
     pub model: Option<String>,
+    pub api_format: Option<String>,
     pub statuses: Option<Vec<String>>,
+    pub is_stream: Option<bool>,
+    pub error_only: bool,
     pub limit: Option<usize>,
+    pub offset: Option<usize>,
+    pub newest_first: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum UsageAuditAggregationGroupBy {
+    Model,
+    Provider,
+    ApiFormat,
+    User,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct UsageAuditAggregationQuery {
+    pub created_from_unix_secs: u64,
+    pub created_until_unix_secs: u64,
+    pub group_by: UsageAuditAggregationGroupBy,
+    pub limit: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
+pub struct UsageAuditSummaryQuery {
+    pub created_from_unix_secs: u64,
+    pub created_until_unix_secs: u64,
+    pub user_id: Option<String>,
+    pub provider_name: Option<String>,
+    pub model: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct StoredUsageAuditAggregation {
+    pub group_key: String,
+    pub display_name: Option<String>,
+    pub secondary_name: Option<String>,
+    pub request_count: u64,
+    pub total_tokens: u64,
+    pub output_tokens: u64,
+    pub effective_input_tokens: u64,
+    pub total_input_context: u64,
+    pub cache_creation_tokens: u64,
+    pub cache_creation_ephemeral_5m_tokens: u64,
+    pub cache_creation_ephemeral_1h_tokens: u64,
+    pub cache_read_tokens: u64,
+    pub total_cost_usd: f64,
+    pub actual_total_cost_usd: f64,
+    pub avg_response_time_ms: Option<f64>,
+    pub success_count: Option<u64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
+pub struct StoredUsageAuditSummary {
+    pub total_requests: u64,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub recorded_total_tokens: u64,
+    pub cache_creation_tokens: u64,
+    pub cache_creation_ephemeral_5m_tokens: u64,
+    pub cache_creation_ephemeral_1h_tokens: u64,
+    pub cache_read_tokens: u64,
+    pub total_cost_usd: f64,
+    pub actual_total_cost_usd: f64,
+    pub cache_creation_cost_usd: f64,
+    pub cache_read_cost_usd: f64,
+    pub total_response_time_ms: f64,
+    pub error_requests: u64,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum UsageTimeSeriesGranularity {
+    Hour,
+    Day,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct UsageTimeSeriesQuery {
+    pub created_from_unix_secs: u64,
+    pub created_until_unix_secs: u64,
+    pub granularity: UsageTimeSeriesGranularity,
+    pub tz_offset_minutes: i32,
+    pub user_id: Option<String>,
+    pub provider_name: Option<String>,
+    pub model: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
+pub struct StoredUsageTimeSeriesBucket {
+    pub bucket_key: String,
+    pub total_requests: u64,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cache_creation_tokens: u64,
+    pub cache_read_tokens: u64,
+    pub total_cost_usd: f64,
+    pub total_response_time_ms: f64,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum UsageLeaderboardGroupBy {
+    Model,
+    User,
+    ApiKey,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct UsageLeaderboardQuery {
+    pub created_from_unix_secs: u64,
+    pub created_until_unix_secs: u64,
+    pub group_by: UsageLeaderboardGroupBy,
+    pub user_id: Option<String>,
+    pub provider_name: Option<String>,
+    pub model: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
+pub struct StoredUsageLeaderboardSummary {
+    pub group_key: String,
+    pub legacy_name: Option<String>,
+    pub request_count: u64,
+    pub total_tokens: u64,
+    pub total_cost_usd: f64,
 }
 
 #[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
@@ -583,6 +709,31 @@ pub trait UsageReadRepository: Send + Sync {
         query: &UsageAuditListQuery,
     ) -> Result<Vec<StoredRequestUsageAudit>, crate::DataLayerError>;
 
+    async fn count_usage_audits(
+        &self,
+        query: &UsageAuditListQuery,
+    ) -> Result<u64, crate::DataLayerError>;
+
+    async fn aggregate_usage_audits(
+        &self,
+        query: &UsageAuditAggregationQuery,
+    ) -> Result<Vec<StoredUsageAuditAggregation>, crate::DataLayerError>;
+
+    async fn summarize_usage_audits(
+        &self,
+        query: &UsageAuditSummaryQuery,
+    ) -> Result<StoredUsageAuditSummary, crate::DataLayerError>;
+
+    async fn summarize_usage_time_series(
+        &self,
+        query: &UsageTimeSeriesQuery,
+    ) -> Result<Vec<StoredUsageTimeSeriesBucket>, crate::DataLayerError>;
+
+    async fn summarize_usage_leaderboard(
+        &self,
+        query: &UsageLeaderboardQuery,
+    ) -> Result<Vec<StoredUsageLeaderboardSummary>, crate::DataLayerError>;
+
     async fn list_recent_usage_audits(
         &self,
         user_id: Option<&str>,

crates/aether-data/src/repository/usage/memory.rs

@@ -2,9 +2,13 @@ use std::collections::BTreeMap;
 use std::sync::RwLock;
 
 use aether_data_contracts::repository::usage::{
-    parse_usage_body_ref, usage_body_ref, UsageBodyField,
+    parse_usage_body_ref, usage_body_ref, StoredUsageAuditAggregation, StoredUsageAuditSummary,
+    StoredUsageLeaderboardSummary, StoredUsageTimeSeriesBucket, UsageAuditAggregationGroupBy,
+    UsageAuditAggregationQuery, UsageAuditSummaryQuery, UsageBodyField, UsageLeaderboardGroupBy,
+    UsageLeaderboardQuery, UsageTimeSeriesGranularity, UsageTimeSeriesQuery,
 };
 use async_trait::async_trait;
+use chrono::Utc;
 use serde_json::Value;
 
 use super::{
@@ -109,6 +113,309 @@ fn usage_status_is_lifecycle(status: &str) -> bool {
     matches!(status, "pending" | "streaming")
 }
 
+fn usage_matches_list_query(item: &StoredRequestUsageAudit, query: &UsageAuditListQuery) -> bool {
+    // The field is historically named `created_at_unix_ms`, but usage audit rows
+    // across gateway handlers, SQL repositories and tests are stored as epoch seconds.
+    if let Some(created_from_unix_secs) = query.created_from_unix_secs {
+        if item.created_at_unix_ms < created_from_unix_secs {
+            return false;
+        }
+    }
+    if let Some(created_until_unix_secs) = query.created_until_unix_secs {
+        if item.created_at_unix_ms >= created_until_unix_secs {
+            return false;
+        }
+    }
+    if let Some(user_id) = query.user_id.as_deref() {
+        if item.user_id.as_deref() != Some(user_id) {
+            return false;
+        }
+    }
+    if let Some(provider_name) = query.provider_name.as_deref() {
+        if item.provider_name != provider_name {
+            return false;
+        }
+    }
+    if let Some(model) = query.model.as_deref() {
+        if item.model != model {
+            return false;
+        }
+    }
+    if let Some(api_format) = query.api_format.as_deref() {
+        if item.api_format.as_deref() != Some(api_format) {
+            return false;
+        }
+    }
+    if let Some(statuses) = query.statuses.as_ref() {
+        if !statuses.iter().any(|status| status == &item.status) {
+            return false;
+        }
+    }
+    if let Some(is_stream) = query.is_stream {
+        if item.is_stream != is_stream {
+            return false;
+        }
+    }
+    if query.error_only
+        && item.status != "failed"
+        && item.status_code.unwrap_or_default() < 400
+        && item
+            .error_message
+            .as_deref()
+            .map(str::trim)
+            .unwrap_or_default()
+            .is_empty()
+    {
+        return false;
+    }
+
+    true
+}
+
+fn usage_matches_summary_query(
+    item: &StoredRequestUsageAudit,
+    query: &UsageAuditSummaryQuery,
+) -> bool {
+    if item.created_at_unix_ms < query.created_from_unix_secs
+        || item.created_at_unix_ms >= query.created_until_unix_secs
+    {
+        return false;
+    }
+    if let Some(user_id) = query.user_id.as_deref() {
+        if item.user_id.as_deref() != Some(user_id) {
+            return false;
+        }
+    }
+    if let Some(provider_name) = query.provider_name.as_deref() {
+        if item.provider_name != provider_name {
+            return false;
+        }
+    }
+    if let Some(model) = query.model.as_deref() {
+        if item.model != model {
+            return false;
+        }
+    }
+    true
+}
+
+fn usage_matches_time_series_query(
+    item: &StoredRequestUsageAudit,
+    query: &UsageTimeSeriesQuery,
+) -> bool {
+    if item.created_at_unix_ms < query.created_from_unix_secs
+        || item.created_at_unix_ms >= query.created_until_unix_secs
+    {
+        return false;
+    }
+    if let Some(user_id) = query.user_id.as_deref() {
+        if item.user_id.as_deref() != Some(user_id) {
+            return false;
+        }
+    }
+    if let Some(provider_name) = query.provider_name.as_deref() {
+        if item.provider_name != provider_name {
+            return false;
+        }
+    }
+    if let Some(model) = query.model.as_deref() {
+        if item.model != model {
+            return false;
+        }
+    }
+    true
+}
+
+fn usage_time_series_bucket_key(
+    item: &StoredRequestUsageAudit,
+    granularity: UsageTimeSeriesGranularity,
+    tz_offset_minutes: i32,
+) -> Option<String> {
+    let timestamp =
+        chrono::DateTime::<Utc>::from_timestamp(i64::try_from(item.created_at_unix_ms).ok()?, 0)?;
+    let local =
+        timestamp.checked_add_signed(chrono::Duration::minutes(i64::from(tz_offset_minutes)))?;
+    Some(match granularity {
+        UsageTimeSeriesGranularity::Day => local.date_naive().to_string(),
+        UsageTimeSeriesGranularity::Hour => local.format("%Y-%m-%dT%H:00:00+00:00").to_string(),
+    })
+}
+
+fn usage_matches_leaderboard_query(
+    item: &StoredRequestUsageAudit,
+    query: &UsageLeaderboardQuery,
+) -> bool {
+    if item.created_at_unix_ms < query.created_from_unix_secs
+        || item.created_at_unix_ms >= query.created_until_unix_secs
+        || matches!(item.status.as_str(), "pending" | "streaming")
+        || matches!(item.provider_name.as_str(), "unknown" | "pending")
+    {
+        return false;
+    }
+    if let Some(user_id) = query.user_id.as_deref() {
+        if item.user_id.as_deref() != Some(user_id) {
+            return false;
+        }
+    }
+    if let Some(provider_name) = query.provider_name.as_deref() {
+        if item.provider_name != provider_name {
+            return false;
+        }
+    }
+    if let Some(model) = query.model.as_deref() {
+        if item.model != model {
+            return false;
+        }
+    }
+    true
+}
+
+fn sort_usage_items(items: &mut [StoredRequestUsageAudit], newest_first: bool) {
+    items.sort_by(|left, right| {
+        let created_order = if newest_first {
+            right.created_at_unix_ms.cmp(&left.created_at_unix_ms)
+        } else {
+            left.created_at_unix_ms.cmp(&right.created_at_unix_ms)
+        };
+        if newest_first {
+            created_order.then_with(|| left.id.cmp(&right.id))
+        } else {
+            created_order.then_with(|| left.request_id.cmp(&right.request_id))
+        }
+    });
+}
+
+fn usage_cache_creation_tokens(item: &StoredRequestUsageAudit) -> u64 {
+    let classified = item
+        .cache_creation_ephemeral_5m_input_tokens
+        .saturating_add(item.cache_creation_ephemeral_1h_input_tokens);
+    if item.cache_creation_input_tokens == 0 && classified > 0 {
+        classified
+    } else {
+        item.cache_creation_input_tokens
+    }
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum UsageApiFamily {
+    OpenAi,
+    Claude,
+    Gemini,
+    Unknown,
+}
+
+fn usage_api_family(api_format: Option<&str>) -> UsageApiFamily {
+    let Some(api_format) = api_format else {
+        return UsageApiFamily::Unknown;
+    };
+    let family = api_format
+        .split(':')
+        .next()
+        .unwrap_or_default()
+        .trim()
+        .to_ascii_lowercase();
+    match family.as_str() {
+        "openai" => UsageApiFamily::OpenAi,
+        "claude" | "anthropic" => UsageApiFamily::Claude,
+        "gemini" | "google" => UsageApiFamily::Gemini,
+        _ => UsageApiFamily::Unknown,
+    }
+}
+
+fn normalize_usage_input_tokens(
+    api_format: Option<&str>,
+    input_tokens: i64,
+    cache_read_tokens: i64,
+) -> i64 {
+    if input_tokens <= 0 {
+        return input_tokens.max(0);
+    }
+    if cache_read_tokens <= 0 {
+        return input_tokens;
+    }
+
+    match usage_api_family(api_format) {
+        UsageApiFamily::OpenAi | UsageApiFamily::Gemini => {
+            (input_tokens - cache_read_tokens).max(0)
+        }
+        UsageApiFamily::Claude | UsageApiFamily::Unknown => input_tokens,
+    }
+}
+
+fn normalize_usage_total_input_context(
+    api_format: Option<&str>,
+    input_tokens: i64,
+    cache_creation_tokens: i64,
+    cache_read_tokens: i64,
+) -> i64 {
+    let normalized_input_tokens = input_tokens.max(0);
+    let normalized_cache_creation_tokens = cache_creation_tokens.max(0);
+    let normalized_cache_read_tokens = cache_read_tokens.max(0);
+
+    let fresh_input_tokens = match usage_api_family(api_format) {
+        UsageApiFamily::Claude => {
+            normalized_input_tokens.saturating_add(normalized_cache_creation_tokens)
+        }
+        UsageApiFamily::OpenAi | UsageApiFamily::Gemini => normalize_usage_input_tokens(
+            api_format,
+            normalized_input_tokens,
+            normalized_cache_read_tokens,
+        ),
+        UsageApiFamily::Unknown => {
+            if normalized_cache_creation_tokens > 0 {
+                normalized_input_tokens.saturating_add(normalized_cache_creation_tokens)
+            } else {
+                normalized_input_tokens
+            }
+        }
+    };
+
+    fresh_input_tokens.saturating_add(normalized_cache_read_tokens)
+}
+
+fn usage_total_input_context(item: &StoredRequestUsageAudit) -> u64 {
+    let api_format = item
+        .endpoint_api_format
+        .as_deref()
+        .or(item.api_format.as_deref());
+    let input_tokens = i64::try_from(item.input_tokens).unwrap_or(i64::MAX);
+    let cache_creation_tokens =
+        i64::try_from(usage_cache_creation_tokens(item)).unwrap_or(i64::MAX);
+    let cache_read_tokens = i64::try_from(item.cache_read_input_tokens).unwrap_or(i64::MAX);
+    normalize_usage_total_input_context(
+        api_format,
+        input_tokens,
+        cache_creation_tokens,
+        cache_read_tokens,
+    ) as u64
+}
+
+fn usage_effective_input_tokens(item: &StoredRequestUsageAudit) -> u64 {
+    let api_format = item
+        .endpoint_api_format
+        .as_deref()
+        .or(item.api_format.as_deref());
+    let input_tokens = i64::try_from(item.input_tokens).unwrap_or(i64::MAX);
+    let cache_read_tokens = i64::try_from(item.cache_read_input_tokens).unwrap_or(i64::MAX);
+    normalize_usage_input_tokens(api_format, input_tokens, cache_read_tokens) as u64
+}
+
+fn usage_is_success(item: &StoredRequestUsageAudit) -> bool {
+    matches!(
+        item.status.as_str(),
+        "completed" | "success" | "ok" | "billed" | "settled"
+    ) && item.status_code.is_none_or(|code| code < 400)
+}
+
+fn usage_provider_display_name(item: &StoredRequestUsageAudit) -> Option<String> {
+    let provider_name = item.provider_name.trim();
+    if provider_name.is_empty() || matches!(provider_name, "unknown" | "pending") {
+        None
+    } else {
+        Some(item.provider_name.clone())
+    }
+}
+
 #[async_trait]
 impl UsageReadRepository for InMemoryUsageReadRepository {
     async fn find_by_id(
@@ -172,54 +479,302 @@ impl UsageReadRepository for InMemoryUsageReadRepository {
             .read()
             .expect("usage repository lock")
             .values()
-            .filter(|item| {
-                // The field is historically named `created_at_unix_ms`, but usage audit rows
-                // across gateway handlers, SQL repositories and tests are stored as epoch seconds.
-                if let Some(created_from_unix_secs) = query.created_from_unix_secs {
-                    if item.created_at_unix_ms < created_from_unix_secs {
-                        return false;
-                    }
-                }
-                if let Some(created_until_unix_secs) = query.created_until_unix_secs {
-                    if item.created_at_unix_ms >= created_until_unix_secs {
-                        return false;
-                    }
-                }
-                if let Some(user_id) = query.user_id.as_deref() {
-                    if item.user_id.as_deref() != Some(user_id) {
-                        return false;
-                    }
-                }
-                if let Some(provider_name) = query.provider_name.as_deref() {
-                    if item.provider_name != provider_name {
-                        return false;
-                    }
-                }
-                if let Some(model) = query.model.as_deref() {
-                    if item.model != model {
-                        return false;
-                    }
-                }
-                if let Some(statuses) = query.statuses.as_ref() {
-                    if !statuses.iter().any(|s| s == &item.status) {
-                        return false;
-                    }
-                }
-                true
-            })
+            .filter(|item| usage_matches_list_query(item, query))
             .cloned()
             .collect();
-        items.sort_by(|left, right| {
-            left.created_at_unix_ms
-                .cmp(&right.created_at_unix_ms)
-                .then_with(|| left.request_id.cmp(&right.request_id))
-        });
+        sort_usage_items(&mut items, query.newest_first);
+        if let Some(offset) = query.offset {
+            if offset >= items.len() {
+                items.clear();
+            } else {
+                items.drain(..offset);
+            }
+        }
         if let Some(limit) = query.limit {
             items.truncate(limit);
         }
         Ok(items)
     }
 
+    async fn count_usage_audits(&self, query: &UsageAuditListQuery) -> Result<u64, DataLayerError> {
+        Ok(self
+            .by_request_id
+            .read()
+            .expect("usage repository lock")
+            .values()
+            .filter(|item| usage_matches_list_query(item, query))
+            .count() as u64)
+    }
+
+    async fn aggregate_usage_audits(
+        &self,
+        query: &UsageAuditAggregationQuery,
+    ) -> Result<Vec<StoredUsageAuditAggregation>, DataLayerError> {
+        #[derive(Default)]
+        struct AggregateBucket {
+            display_name: Option<String>,
+            secondary_name: Option<String>,
+            request_count: u64,
+            total_tokens: u64,
+            output_tokens: u64,
+            effective_input_tokens: u64,
+            total_input_context: u64,
+            cache_creation_tokens: u64,
+            cache_creation_ephemeral_5m_tokens: u64,
+            cache_creation_ephemeral_1h_tokens: u64,
+            cache_read_tokens: u64,
+            total_cost_usd: f64,
+            actual_total_cost_usd: f64,
+            response_time_ms_sum: u64,
+            success_count: u64,
+        }
+
+        let mut grouped: BTreeMap<String, AggregateBucket> = BTreeMap::new();
+        for item in self
+            .by_request_id
+            .read()
+            .expect("usage repository lock")
+            .values()
+        {
+            if item.created_at_unix_ms < query.created_from_unix_secs
+                || item.created_at_unix_ms >= query.created_until_unix_secs
+                || matches!(item.status.as_str(), "pending" | "streaming")
+            {
+                continue;
+            }
+
+            let group_key = match query.group_by {
+                UsageAuditAggregationGroupBy::Model => item.model.clone(),
+                UsageAuditAggregationGroupBy::Provider => item
+                    .provider_id
+                    .clone()
+                    .unwrap_or_else(|| "unknown".to_string()),
+                UsageAuditAggregationGroupBy::ApiFormat => item
+                    .api_format
+                    .clone()
+                    .unwrap_or_else(|| "unknown".to_string()),
+                UsageAuditAggregationGroupBy::User => match item.user_id.clone() {
+                    Some(value) => value,
+                    None => continue,
+                },
+            };
+            let bucket = grouped.entry(group_key).or_default();
+            if matches!(query.group_by, UsageAuditAggregationGroupBy::Provider)
+                && (bucket.display_name.is_none()
+                    || bucket.display_name.as_deref() == Some("Unknown"))
+            {
+                bucket.display_name =
+                    usage_provider_display_name(item).or(Some("Unknown".to_string()));
+            }
+            bucket.request_count = bucket.request_count.saturating_add(1);
+            bucket.total_tokens = bucket.total_tokens.saturating_add(item.total_tokens);
+            bucket.output_tokens = bucket.output_tokens.saturating_add(item.output_tokens);
+            bucket.effective_input_tokens = bucket
+                .effective_input_tokens
+                .saturating_add(usage_effective_input_tokens(item));
+            bucket.total_input_context = bucket
+                .total_input_context
+                .saturating_add(usage_total_input_context(item));
+            bucket.cache_creation_tokens = bucket
+                .cache_creation_tokens
+                .saturating_add(usage_cache_creation_tokens(item));
+            bucket.cache_creation_ephemeral_5m_tokens = bucket
+                .cache_creation_ephemeral_5m_tokens
+                .saturating_add(item.cache_creation_ephemeral_5m_input_tokens);
+            bucket.cache_creation_ephemeral_1h_tokens = bucket
+                .cache_creation_ephemeral_1h_tokens
+                .saturating_add(item.cache_creation_ephemeral_1h_input_tokens);
+            bucket.cache_read_tokens = bucket
+                .cache_read_tokens
+                .saturating_add(item.cache_read_input_tokens);
+            bucket.total_cost_usd += item.total_cost_usd;
+            bucket.actual_total_cost_usd += item.actual_total_cost_usd;
+            bucket.response_time_ms_sum = bucket
+                .response_time_ms_sum
+                .saturating_add(item.response_time_ms.unwrap_or_default());
+            bucket.success_count = bucket
+                .success_count
+                .saturating_add(if usage_is_success(item) { 1 } else { 0 });
+        }
+
+        let mut items = grouped
+            .into_iter()
+            .map(|(group_key, bucket)| StoredUsageAuditAggregation {
+                group_key,
+                display_name: bucket.display_name,
+                secondary_name: bucket.secondary_name,
+                request_count: bucket.request_count,
+                total_tokens: bucket.total_tokens,
+                output_tokens: bucket.output_tokens,
+                effective_input_tokens: bucket.effective_input_tokens,
+                total_input_context: bucket.total_input_context,
+                cache_creation_tokens: bucket.cache_creation_tokens,
+                cache_creation_ephemeral_5m_tokens: bucket.cache_creation_ephemeral_5m_tokens,
+                cache_creation_ephemeral_1h_tokens: bucket.cache_creation_ephemeral_1h_tokens,
+                cache_read_tokens: bucket.cache_read_tokens,
+                total_cost_usd: bucket.total_cost_usd,
+                actual_total_cost_usd: bucket.actual_total_cost_usd,
+                avg_response_time_ms: match query.group_by {
+                    UsageAuditAggregationGroupBy::Provider
+                    | UsageAuditAggregationGroupBy::ApiFormat => {
+                        Some(if bucket.request_count == 0 {
+                            0.0
+                        } else {
+                            bucket.response_time_ms_sum as f64 / bucket.request_count as f64
+                        })
+                    }
+                    _ => None,
+                },
+                success_count: match query.group_by {
+                    UsageAuditAggregationGroupBy::Provider => Some(bucket.success_count),
+                    _ => None,
+                },
+            })
+            .collect::<Vec<_>>();
+
+        items.sort_by(|left, right| {
+            right
+                .request_count
+                .cmp(&left.request_count)
+                .then_with(|| left.group_key.cmp(&right.group_key))
+        });
+        items.truncate(query.limit);
+        Ok(items)
+    }
+
+    async fn summarize_usage_audits(
+        &self,
+        query: &UsageAuditSummaryQuery,
+    ) -> Result<StoredUsageAuditSummary, DataLayerError> {
+        let mut summary = StoredUsageAuditSummary::default();
+        for item in self
+            .by_request_id
+            .read()
+            .expect("usage repository lock")
+            .values()
+        {
+            if !usage_matches_summary_query(item, query) {
+                continue;
+            }
+            summary.total_requests = summary.total_requests.saturating_add(1);
+            summary.input_tokens = summary.input_tokens.saturating_add(item.input_tokens);
+            summary.output_tokens = summary.output_tokens.saturating_add(item.output_tokens);
+            summary.recorded_total_tokens = summary
+                .recorded_total_tokens
+                .saturating_add(item.total_tokens);
+            summary.cache_creation_tokens = summary
+                .cache_creation_tokens
+                .saturating_add(usage_cache_creation_tokens(item));
+            summary.cache_creation_ephemeral_5m_tokens = summary
+                .cache_creation_ephemeral_5m_tokens
+                .saturating_add(item.cache_creation_ephemeral_5m_input_tokens);
+            summary.cache_creation_ephemeral_1h_tokens = summary
+                .cache_creation_ephemeral_1h_tokens
+                .saturating_add(item.cache_creation_ephemeral_1h_input_tokens);
+            summary.cache_read_tokens = summary
+                .cache_read_tokens
+                .saturating_add(item.cache_read_input_tokens);
+            summary.total_cost_usd += item.total_cost_usd;
+            summary.actual_total_cost_usd += item.actual_total_cost_usd;
+            summary.cache_creation_cost_usd += item.cache_creation_cost_usd;
+            summary.cache_read_cost_usd += item.cache_read_cost_usd;
+            summary.total_response_time_ms += item.response_time_ms.unwrap_or(0) as f64;
+            if item.status_code.is_some_and(|value| value >= 400) || item.error_message.is_some() {
+                summary.error_requests = summary.error_requests.saturating_add(1);
+            }
+        }
+        Ok(summary)
+    }
+
+    async fn summarize_usage_time_series(
+        &self,
+        query: &UsageTimeSeriesQuery,
+    ) -> Result<Vec<StoredUsageTimeSeriesBucket>, DataLayerError> {
+        let mut buckets = BTreeMap::<String, StoredUsageTimeSeriesBucket>::new();
+        for item in self
+            .by_request_id
+            .read()
+            .expect("usage repository lock")
+            .values()
+        {
+            if !usage_matches_time_series_query(item, query) {
+                continue;
+            }
+            let Some(bucket_key) =
+                usage_time_series_bucket_key(item, query.granularity, query.tz_offset_minutes)
+            else {
+                continue;
+            };
+            let bucket =
+                buckets
+                    .entry(bucket_key.clone())
+                    .or_insert_with(|| StoredUsageTimeSeriesBucket {
+                        bucket_key,
+                        ..Default::default()
+                    });
+            bucket.total_requests = bucket.total_requests.saturating_add(1);
+            bucket.input_tokens = bucket.input_tokens.saturating_add(item.input_tokens);
+            bucket.output_tokens = bucket.output_tokens.saturating_add(item.output_tokens);
+            bucket.cache_creation_tokens = bucket
+                .cache_creation_tokens
+                .saturating_add(item.cache_creation_input_tokens);
+            bucket.cache_read_tokens = bucket
+                .cache_read_tokens
+                .saturating_add(item.cache_read_input_tokens);
+            bucket.total_cost_usd += item.total_cost_usd;
+            bucket.total_response_time_ms += item.response_time_ms.unwrap_or(0) as f64;
+        }
+        Ok(buckets.into_values().collect())
+    }
+
+    async fn summarize_usage_leaderboard(
+        &self,
+        query: &UsageLeaderboardQuery,
+    ) -> Result<Vec<StoredUsageLeaderboardSummary>, DataLayerError> {
+        let mut grouped = BTreeMap::<String, StoredUsageLeaderboardSummary>::new();
+        for item in self
+            .by_request_id
+            .read()
+            .expect("usage repository lock")
+            .values()
+        {
+            if !usage_matches_leaderboard_query(item, query) {
+                continue;
+            }
+            let (group_key, legacy_name) = match query.group_by {
+                UsageLeaderboardGroupBy::Model => (item.model.clone(), None),
+                UsageLeaderboardGroupBy::User => match item.user_id.clone() {
+                    Some(user_id) => (user_id, item.username.clone()),
+                    None => continue,
+                },
+                UsageLeaderboardGroupBy::ApiKey => match item.api_key_id.clone() {
+                    Some(api_key_id) => (api_key_id, item.api_key_name.clone()),
+                    None => continue,
+                },
+            };
+            let entry =
+                grouped
+                    .entry(group_key.clone())
+                    .or_insert_with(|| StoredUsageLeaderboardSummary {
+                        group_key,
+                        legacy_name: legacy_name.clone(),
+                        ..Default::default()
+                    });
+            if entry.legacy_name.is_none() {
+                entry.legacy_name = legacy_name;
+            }
+            entry.request_count = entry.request_count.saturating_add(1);
+            entry.total_tokens = entry.total_tokens.saturating_add(
+                item.input_tokens
+                    .saturating_add(item.output_tokens)
+                    .saturating_add(item.cache_creation_input_tokens)
+                    .saturating_add(item.cache_read_input_tokens),
+            );
+            entry.total_cost_usd += item.total_cost_usd;
+        }
+        Ok(grouped.into_values().collect())
+    }
+
     async fn list_recent_usage_audits(
         &self,
         user_id: Option<&str>,

crates/aether-data/src/repository/usage/mod.rs

@@ -4,8 +4,12 @@ mod sql;
 #[allow(unused_imports)]
 pub(crate) use aether_data_contracts::repository::usage::{
     StoredProviderApiKeyUsageSummary, StoredProviderUsageSummary, StoredProviderUsageWindow,
-    StoredRequestUsageAudit, StoredUsageDailySummary, UpsertUsageRecord, UsageAuditListQuery,
-    UsageDailyHeatmapQuery, UsageReadRepository, UsageRepository, UsageWriteRepository,
+    StoredRequestUsageAudit, StoredUsageAuditAggregation, StoredUsageAuditSummary,
+    StoredUsageDailySummary, StoredUsageLeaderboardSummary, StoredUsageTimeSeriesBucket,
+    UpsertUsageRecord, UsageAuditAggregationGroupBy, UsageAuditAggregationQuery,
+    UsageAuditListQuery, UsageAuditSummaryQuery, UsageDailyHeatmapQuery, UsageLeaderboardGroupBy,
+    UsageLeaderboardQuery, UsageReadRepository, UsageRepository, UsageTimeSeriesGranularity,
+    UsageTimeSeriesQuery, UsageWriteRepository,
 };
 pub use memory::InMemoryUsageReadRepository;
 pub use sql::SqlxUsageReadRepository;

crates/aether-data/src/repository/usage/sql.rs

@@ -1,5 +1,8 @@
 use aether_data_contracts::repository::usage::{
-    parse_usage_body_ref, usage_body_ref, UsageBodyField,
+    parse_usage_body_ref, usage_body_ref, StoredUsageAuditAggregation, StoredUsageAuditSummary,
+    StoredUsageLeaderboardSummary, StoredUsageTimeSeriesBucket, UsageAuditAggregationGroupBy,
+    UsageAuditAggregationQuery, UsageAuditSummaryQuery, UsageBodyField, UsageLeaderboardGroupBy,
+    UsageLeaderboardQuery, UsageTimeSeriesGranularity, UsageTimeSeriesQuery,
 };
 use async_trait::async_trait;
 use flate2::{read::GzDecoder, write::GzEncoder, Compression};
@@ -620,6 +623,93 @@ LEFT JOIN usage_settlement_snapshots
   ON usage_settlement_snapshots.request_id = "usage".request_id
 "#;
 
+struct UsageAuditAggregationSqlFragments {
+    filtered_extra_where: &'static str,
+    group_key_expr: &'static str,
+    display_name_expr: &'static str,
+    secondary_name_expr: &'static str,
+    aggregate_display_name_expr: &'static str,
+    aggregate_secondary_name_expr: &'static str,
+    avg_response_time_expr: &'static str,
+    success_count_expr: &'static str,
+}
+
+fn usage_audit_aggregation_sql_fragments(
+    group_by: UsageAuditAggregationGroupBy,
+) -> UsageAuditAggregationSqlFragments {
+    match group_by {
+        UsageAuditAggregationGroupBy::Model => UsageAuditAggregationSqlFragments {
+            filtered_extra_where: "",
+            group_key_expr: "model",
+            display_name_expr: "NULL::varchar",
+            secondary_name_expr: "NULL::varchar",
+            aggregate_display_name_expr: "NULL::varchar",
+            aggregate_secondary_name_expr: "NULL::varchar",
+            avg_response_time_expr: "NULL::DOUBLE PRECISION",
+            success_count_expr: "NULL::BIGINT",
+        },
+        UsageAuditAggregationGroupBy::Provider => UsageAuditAggregationSqlFragments {
+            filtered_extra_where: "",
+            group_key_expr: "provider_group_key",
+            display_name_expr: "provider_display_name",
+            secondary_name_expr: "NULL::varchar",
+            aggregate_display_name_expr:
+                "COALESCE(MAX(NULLIF(display_name, 'Unknown')), 'Unknown')",
+            aggregate_secondary_name_expr: "NULL::varchar",
+            avg_response_time_expr: "AVG(response_time_ms::DOUBLE PRECISION)",
+            success_count_expr: "COALESCE(SUM(success_flag), 0)::BIGINT",
+        },
+        UsageAuditAggregationGroupBy::ApiFormat => UsageAuditAggregationSqlFragments {
+            filtered_extra_where: "",
+            group_key_expr: "api_format_group_key",
+            display_name_expr: "NULL::varchar",
+            secondary_name_expr: "NULL::varchar",
+            aggregate_display_name_expr: "NULL::varchar",
+            aggregate_secondary_name_expr: "NULL::varchar",
+            avg_response_time_expr: "AVG(response_time_ms::DOUBLE PRECISION)",
+            success_count_expr: "NULL::BIGINT",
+        },
+        UsageAuditAggregationGroupBy::User => UsageAuditAggregationSqlFragments {
+            filtered_extra_where: " AND \"usage\".user_id IS NOT NULL",
+            group_key_expr: "user_id",
+            display_name_expr: "NULL::varchar",
+            secondary_name_expr: "NULL::varchar",
+            aggregate_display_name_expr: "NULL::varchar",
+            aggregate_secondary_name_expr: "NULL::varchar",
+            avg_response_time_expr: "NULL::DOUBLE PRECISION",
+            success_count_expr: "NULL::BIGINT",
+        },
+    }
+}
+
+struct UsageLeaderboardSqlFragments {
+    filtered_extra_where: &'static str,
+    group_key_expr: &'static str,
+    legacy_name_expr: &'static str,
+}
+
+fn usage_leaderboard_sql_fragments(
+    group_by: UsageLeaderboardGroupBy,
+) -> UsageLeaderboardSqlFragments {
+    match group_by {
+        UsageLeaderboardGroupBy::Model => UsageLeaderboardSqlFragments {
+            filtered_extra_where: "",
+            group_key_expr: "\"usage\".model",
+            legacy_name_expr: "NULL::varchar",
+        },
+        UsageLeaderboardGroupBy::User => UsageLeaderboardSqlFragments {
+            filtered_extra_where: " AND \"usage\".user_id IS NOT NULL",
+            group_key_expr: "\"usage\".user_id",
+            legacy_name_expr: "NULLIF(BTRIM(\"usage\".username), '')",
+        },
+        UsageLeaderboardGroupBy::ApiKey => UsageLeaderboardSqlFragments {
+            filtered_extra_where: " AND \"usage\".api_key_id IS NOT NULL",
+            group_key_expr: "\"usage\".api_key_id",
+            legacy_name_expr: "NULLIF(BTRIM(\"usage\".api_key_name), '')",
+        },
+    }
+}
+
 const LIST_RECENT_USAGE_AUDITS_PREFIX: &str = r#"
 SELECT
   "usage".id,
@@ -1206,9 +1296,17 @@ impl SqlxUsageReadRepository {
                 .push("\"usage\".model = ")
                 .push_bind(model.to_string());
         }
+        if let Some(api_format) = query.api_format.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".api_format = ")
+                .push_bind(api_format.to_string());
+        }
         if let Some(statuses) = query.statuses.as_deref() {
             if !statuses.is_empty() {
                 builder.push(if has_where { " AND " } else { " WHERE " });
+                has_where = true;
                 builder.push("\"usage\".status IN (");
                 let mut separated = builder.separated(", ");
                 for status in statuses {
@@ -1217,11 +1315,31 @@ impl SqlxUsageReadRepository {
                 separated.push_unseparated(")");
             }
         }
+        if let Some(is_stream) = query.is_stream {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder.push("\"usage\".is_stream = ").push_bind(is_stream);
+        }
+        if query.error_only {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            builder.push(
+                "(\"usage\".status = 'failed' \
+OR COALESCE(\"usage\".status_code, 0) >= 400 \
+OR (\"usage\".error_message IS NOT NULL AND BTRIM(\"usage\".error_message) <> ''))",
+            );
+        }
 
+        if query.newest_first {
+            builder.push(" ORDER BY \"usage\".created_at DESC, \"usage\".id ASC");
+        } else {
             builder.push(" ORDER BY \"usage\".created_at ASC, \"usage\".request_id ASC");
+        }
         if let Some(limit) = query.limit {
             builder.push(" LIMIT ").push_bind(limit as i64);
         }
+        if let Some(offset) = query.offset {
+            builder.push(" OFFSET ").push_bind(offset as i64);
+        }
         let query = builder.build();
         let mut rows = query.fetch(&self.pool);
         let mut items = Vec::new();
@@ -1231,6 +1349,626 @@ impl SqlxUsageReadRepository {
         Ok(items)
     }
 
+    pub async fn count_usage_audits(
+        &self,
+        query: &UsageAuditListQuery,
+    ) -> Result<u64, DataLayerError> {
+        let mut builder =
+            QueryBuilder::<Postgres>::new(r#"SELECT COUNT(*)::BIGINT AS total FROM "usage""#);
+        let mut has_where = false;
+
+        if let Some(created_from_unix_secs) = query.created_from_unix_secs {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".created_at >= TO_TIMESTAMP(")
+                .push_bind(created_from_unix_secs as f64)
+                .push("::double precision)");
+        }
+        if let Some(created_until_unix_secs) = query.created_until_unix_secs {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".created_at < TO_TIMESTAMP(")
+                .push_bind(created_until_unix_secs as f64)
+                .push("::double precision)");
+        }
+        if let Some(user_id) = query.user_id.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".user_id = ")
+                .push_bind(user_id.to_string());
+        }
+        if let Some(provider_name) = query.provider_name.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".provider_name = ")
+                .push_bind(provider_name.to_string());
+        }
+        if let Some(model) = query.model.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".model = ")
+                .push_bind(model.to_string());
+        }
+        if let Some(api_format) = query.api_format.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".api_format = ")
+                .push_bind(api_format.to_string());
+        }
+        if let Some(statuses) = query.statuses.as_deref() {
+            if !statuses.is_empty() {
+                builder.push(if has_where { " AND " } else { " WHERE " });
+                has_where = true;
+                builder.push("\"usage\".status IN (");
+                let mut separated = builder.separated(", ");
+                for status in statuses {
+                    separated.push_bind(status.to_string());
+                }
+                separated.push_unseparated(")");
+            }
+        }
+        if let Some(is_stream) = query.is_stream {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder.push("\"usage\".is_stream = ").push_bind(is_stream);
+        }
+        if query.error_only {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            builder.push(
+                "(\"usage\".status = 'failed' \
+OR COALESCE(\"usage\".status_code, 0) >= 400 \
+OR (\"usage\".error_message IS NOT NULL AND BTRIM(\"usage\".error_message) <> ''))",
+            );
+        }
+
+        let row = builder
+            .build()
+            .fetch_one(&self.pool)
+            .await
+            .map_postgres_err()?;
+        Ok(row.try_get::<i64, _>("total").map_postgres_err()?.max(0) as u64)
+    }
+
+    pub async fn summarize_usage_audits(
+        &self,
+        query: &UsageAuditSummaryQuery,
+    ) -> Result<StoredUsageAuditSummary, DataLayerError> {
+        let mut builder = QueryBuilder::<Postgres>::new(
+            r#"
+SELECT
+  COUNT(*)::BIGINT AS total_requests,
+  COALESCE(SUM(GREATEST(COALESCE("usage".input_tokens, 0), 0)), 0)::BIGINT AS input_tokens,
+  COALESCE(SUM(GREATEST(COALESCE("usage".output_tokens, 0), 0)), 0)::BIGINT AS output_tokens,
+  COALESCE(SUM(GREATEST(COALESCE("usage".total_tokens, 0), 0)), 0)::BIGINT AS recorded_total_tokens,
+  COALESCE(SUM(
+    CASE
+      WHEN COALESCE("usage".cache_creation_input_tokens, 0) = 0
+           AND (
+             COALESCE("usage".cache_creation_input_tokens_5m, 0)
+             + COALESCE("usage".cache_creation_input_tokens_1h, 0)
+           ) > 0
+      THEN COALESCE("usage".cache_creation_input_tokens_5m, 0)
+         + COALESCE("usage".cache_creation_input_tokens_1h, 0)
+      ELSE COALESCE("usage".cache_creation_input_tokens, 0)
+    END
+  ), 0)::BIGINT AS cache_creation_tokens,
+  COALESCE(SUM(GREATEST(COALESCE("usage".cache_creation_input_tokens_5m, 0), 0)), 0)::BIGINT
+    AS cache_creation_ephemeral_5m_tokens,
+  COALESCE(SUM(GREATEST(COALESCE("usage".cache_creation_input_tokens_1h, 0), 0)), 0)::BIGINT
+    AS cache_creation_ephemeral_1h_tokens,
+  COALESCE(SUM(GREATEST(COALESCE("usage".cache_read_input_tokens, 0), 0)), 0)::BIGINT
+    AS cache_read_tokens,
+  COALESCE(SUM(COALESCE(CAST("usage".total_cost_usd AS DOUBLE PRECISION), 0)), 0)
+    AS total_cost_usd,
+  COALESCE(SUM(COALESCE(CAST("usage".actual_total_cost_usd AS DOUBLE PRECISION), 0)), 0)
+    AS actual_total_cost_usd,
+  COALESCE(SUM(COALESCE(CAST("usage".cache_creation_cost_usd AS DOUBLE PRECISION), 0)), 0)
+    AS cache_creation_cost_usd,
+  COALESCE(SUM(COALESCE(CAST("usage".cache_read_cost_usd AS DOUBLE PRECISION), 0)), 0)
+    AS cache_read_cost_usd,
+  COALESCE(SUM(GREATEST(COALESCE("usage".response_time_ms, 0), 0)::DOUBLE PRECISION), 0)
+    AS total_response_time_ms,
+  COALESCE(SUM(
+    CASE
+      WHEN COALESCE("usage".status_code, 0) >= 400 OR "usage".error_message IS NOT NULL THEN 1
+      ELSE 0
+    END
+  ), 0)::BIGINT AS error_requests
+FROM "usage"
+"#,
+        );
+        let mut has_where = false;
+
+        builder.push(if has_where { " AND " } else { " WHERE " });
+        has_where = true;
+        builder
+            .push("\"usage\".created_at >= TO_TIMESTAMP(")
+            .push_bind(query.created_from_unix_secs as f64)
+            .push("::double precision)");
+        builder.push(if has_where { " AND " } else { " WHERE " });
+        builder
+            .push("\"usage\".created_at < TO_TIMESTAMP(")
+            .push_bind(query.created_until_unix_secs as f64)
+            .push("::double precision)");
+        if let Some(user_id) = query.user_id.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".user_id = ")
+                .push_bind(user_id.to_string());
+        }
+        if let Some(provider_name) = query.provider_name.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".provider_name = ")
+                .push_bind(provider_name.to_string());
+        }
+        if let Some(model) = query.model.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            builder
+                .push("\"usage\".model = ")
+                .push_bind(model.to_string());
+        }
+
+        let row = builder
+            .build()
+            .fetch_one(&self.pool)
+            .await
+            .map_postgres_err()?;
+        Ok(StoredUsageAuditSummary {
+            total_requests: row
+                .try_get::<i64, _>("total_requests")
+                .map_postgres_err()?
+                .max(0) as u64,
+            input_tokens: row
+                .try_get::<i64, _>("input_tokens")
+                .map_postgres_err()?
+                .max(0) as u64,
+            output_tokens: row
+                .try_get::<i64, _>("output_tokens")
+                .map_postgres_err()?
+                .max(0) as u64,
+            recorded_total_tokens: row
+                .try_get::<i64, _>("recorded_total_tokens")
+                .map_postgres_err()?
+                .max(0) as u64,
+            cache_creation_tokens: row
+                .try_get::<i64, _>("cache_creation_tokens")
+                .map_postgres_err()?
+                .max(0) as u64,
+            cache_creation_ephemeral_5m_tokens: row
+                .try_get::<i64, _>("cache_creation_ephemeral_5m_tokens")
+                .map_postgres_err()?
+                .max(0) as u64,
+            cache_creation_ephemeral_1h_tokens: row
+                .try_get::<i64, _>("cache_creation_ephemeral_1h_tokens")
+                .map_postgres_err()?
+                .max(0) as u64,
+            cache_read_tokens: row
+                .try_get::<i64, _>("cache_read_tokens")
+                .map_postgres_err()?
+                .max(0) as u64,
+            total_cost_usd: row.try_get::<f64, _>("total_cost_usd").map_postgres_err()?,
+            actual_total_cost_usd: row
+                .try_get::<f64, _>("actual_total_cost_usd")
+                .map_postgres_err()?,
+            cache_creation_cost_usd: row
+                .try_get::<f64, _>("cache_creation_cost_usd")
+                .map_postgres_err()?,
+            cache_read_cost_usd: row
+                .try_get::<f64, _>("cache_read_cost_usd")
+                .map_postgres_err()?,
+            total_response_time_ms: row
+                .try_get::<f64, _>("total_response_time_ms")
+                .map_postgres_err()?,
+            error_requests: row
+                .try_get::<i64, _>("error_requests")
+                .map_postgres_err()?
+                .max(0) as u64,
+        })
+    }
+
+    pub async fn summarize_usage_time_series(
+        &self,
+        query: &UsageTimeSeriesQuery,
+    ) -> Result<Vec<StoredUsageTimeSeriesBucket>, DataLayerError> {
+        let mut builder = QueryBuilder::<Postgres>::new("SELECT ");
+        match query.granularity {
+            UsageTimeSeriesGranularity::Day => {
+                builder
+                    .push("TO_CHAR(date_trunc('day', \"usage\".created_at + (")
+                    .push_bind(query.tz_offset_minutes)
+                    .push("::integer * INTERVAL '1 minute')), 'YYYY-MM-DD') AS bucket_key");
+            }
+            UsageTimeSeriesGranularity::Hour => {
+                builder
+                    .push("TO_CHAR(date_trunc('hour', \"usage\".created_at + (")
+                    .push_bind(query.tz_offset_minutes)
+                    .push("::integer * INTERVAL '1 minute')), 'YYYY-MM-DD\"T\"HH24:00:00+00:00') AS bucket_key");
+            }
+        }
+        builder.push(
+            r#",
+  COUNT(*)::BIGINT AS total_requests,
+  COALESCE(SUM(GREATEST(COALESCE("usage".input_tokens, 0), 0)), 0)::BIGINT AS input_tokens,
+  COALESCE(SUM(GREATEST(COALESCE("usage".output_tokens, 0), 0)), 0)::BIGINT AS output_tokens,
+  COALESCE(SUM(GREATEST(COALESCE("usage".cache_creation_input_tokens, 0), 0)), 0)::BIGINT
+    AS cache_creation_tokens,
+  COALESCE(SUM(GREATEST(COALESCE("usage".cache_read_input_tokens, 0), 0)), 0)::BIGINT
+    AS cache_read_tokens,
+  COALESCE(SUM(COALESCE(CAST("usage".total_cost_usd AS DOUBLE PRECISION), 0)), 0)
+    AS total_cost_usd,
+  COALESCE(SUM(GREATEST(COALESCE("usage".response_time_ms, 0), 0)::DOUBLE PRECISION), 0)
+    AS total_response_time_ms
+FROM "usage"
+"#,
+        );
+        let mut has_where = false;
+
+        builder.push(if has_where { " AND " } else { " WHERE " });
+        has_where = true;
+        builder
+            .push("\"usage\".created_at >= TO_TIMESTAMP(")
+            .push_bind(query.created_from_unix_secs as f64)
+            .push("::double precision)");
+        builder.push(if has_where { " AND " } else { " WHERE " });
+        builder
+            .push("\"usage\".created_at < TO_TIMESTAMP(")
+            .push_bind(query.created_until_unix_secs as f64)
+            .push("::double precision)");
+        if let Some(user_id) = query.user_id.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".user_id = ")
+                .push_bind(user_id.to_string());
+        }
+        if let Some(provider_name) = query.provider_name.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            has_where = true;
+            builder
+                .push("\"usage\".provider_name = ")
+                .push_bind(provider_name.to_string());
+        }
+        if let Some(model) = query.model.as_deref() {
+            builder.push(if has_where { " AND " } else { " WHERE " });
+            builder
+                .push("\"usage\".model = ")
+                .push_bind(model.to_string());
+        }
+        builder.push(" GROUP BY bucket_key ORDER BY bucket_key ASC");
+
+        let mut rows = builder.build().fetch(&self.pool);
+        let mut items = Vec::new();
+        while let Some(row) = rows.try_next().await.map_postgres_err()? {
+            items.push(StoredUsageTimeSeriesBucket {
+                bucket_key: row.try_get::<String, _>("bucket_key").map_postgres_err()?,
+                total_requests: row
+                    .try_get::<i64, _>("total_requests")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                input_tokens: row
+                    .try_get::<i64, _>("input_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                output_tokens: row
+                    .try_get::<i64, _>("output_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                cache_creation_tokens: row
+                    .try_get::<i64, _>("cache_creation_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                cache_read_tokens: row
+                    .try_get::<i64, _>("cache_read_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                total_cost_usd: row.try_get::<f64, _>("total_cost_usd").map_postgres_err()?,
+                total_response_time_ms: row
+                    .try_get::<f64, _>("total_response_time_ms")
+                    .map_postgres_err()?,
+            });
+        }
+        Ok(items)
+    }
+
+    pub async fn summarize_usage_leaderboard(
+        &self,
+        query: &UsageLeaderboardQuery,
+    ) -> Result<Vec<StoredUsageLeaderboardSummary>, DataLayerError> {
+        let fragments = usage_leaderboard_sql_fragments(query.group_by);
+        let sql = format!(
+            r#"
+SELECT
+  {group_key_expr} AS group_key,
+  MAX({legacy_name_expr}) AS legacy_name,
+  COUNT(*)::BIGINT AS request_count,
+  COALESCE(SUM(
+    GREATEST(COALESCE("usage".input_tokens, 0), 0)
+    + GREATEST(COALESCE("usage".output_tokens, 0), 0)
+    + GREATEST(COALESCE("usage".cache_creation_input_tokens, 0), 0)
+    + GREATEST(COALESCE("usage".cache_read_input_tokens, 0), 0)
+  ), 0)::BIGINT AS total_tokens,
+  COALESCE(SUM(COALESCE(CAST("usage".total_cost_usd AS DOUBLE PRECISION), 0)), 0)
+    AS total_cost_usd
+FROM "usage"
+WHERE "usage".created_at >= TO_TIMESTAMP($1::double precision)
+  AND "usage".created_at < TO_TIMESTAMP($2::double precision)
+  AND "usage".status NOT IN ('pending', 'streaming')
+  AND "usage".provider_name NOT IN ('unknown', 'pending')
+  {filtered_extra_where}
+  AND ($3::varchar IS NULL OR "usage".user_id = $3)
+  AND ($4::varchar IS NULL OR "usage".provider_name = $4)
+  AND ($5::varchar IS NULL OR "usage".model = $5)
+GROUP BY group_key
+ORDER BY group_key ASC
+"#,
+            group_key_expr = fragments.group_key_expr,
+            legacy_name_expr = fragments.legacy_name_expr,
+            filtered_extra_where = fragments.filtered_extra_where,
+        );
+        let mut rows = sqlx::query(&sql)
+            .bind(query.created_from_unix_secs as f64)
+            .bind(query.created_until_unix_secs as f64)
+            .bind(query.user_id.as_deref())
+            .bind(query.provider_name.as_deref())
+            .bind(query.model.as_deref())
+            .fetch(&self.pool);
+        let mut items = Vec::new();
+        while let Some(row) = rows.try_next().await.map_postgres_err()? {
+            items.push(StoredUsageLeaderboardSummary {
+                group_key: row.try_get::<String, _>("group_key").map_postgres_err()?,
+                legacy_name: row
+                    .try_get::<Option<String>, _>("legacy_name")
+                    .map_postgres_err()?,
+                request_count: row
+                    .try_get::<i64, _>("request_count")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                total_tokens: row
+                    .try_get::<i64, _>("total_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                total_cost_usd: row.try_get::<f64, _>("total_cost_usd").map_postgres_err()?,
+            });
+        }
+        Ok(items)
+    }
+
+    pub async fn aggregate_usage_audits(
+        &self,
+        query: &UsageAuditAggregationQuery,
+    ) -> Result<Vec<StoredUsageAuditAggregation>, DataLayerError> {
+        let fragments = usage_audit_aggregation_sql_fragments(query.group_by);
+        let sql = format!(
+            r#"
+WITH filtered_usage AS (
+  SELECT
+    "usage".model AS model,
+    "usage".user_id AS user_id,
+    COALESCE("usage".provider_id, 'unknown') AS provider_group_key,
+    CASE
+      WHEN BTRIM(COALESCE("usage".provider_name, '')) = ''
+        OR "usage".provider_name IN ('unknown', 'pending')
+      THEN 'Unknown'
+      ELSE "usage".provider_name
+    END AS provider_display_name,
+    COALESCE("usage".api_format, 'unknown') AS api_format_group_key,
+    GREATEST(COALESCE("usage".input_tokens, 0), 0) AS input_tokens,
+    GREATEST(COALESCE("usage".output_tokens, 0), 0) AS output_tokens,
+    GREATEST(COALESCE("usage".total_tokens, 0), 0) AS total_tokens,
+    CASE
+      WHEN COALESCE("usage".cache_creation_input_tokens, 0) = 0
+           AND (
+             COALESCE("usage".cache_creation_input_tokens_5m, 0)
+             + COALESCE("usage".cache_creation_input_tokens_1h, 0)
+           ) > 0
+      THEN COALESCE("usage".cache_creation_input_tokens_5m, 0)
+         + COALESCE("usage".cache_creation_input_tokens_1h, 0)
+      ELSE COALESCE("usage".cache_creation_input_tokens, 0)
+    END AS cache_creation_tokens,
+    GREATEST(COALESCE("usage".cache_creation_input_tokens_5m, 0), 0)
+      AS cache_creation_ephemeral_5m_tokens,
+    GREATEST(COALESCE("usage".cache_creation_input_tokens_1h, 0), 0)
+      AS cache_creation_ephemeral_1h_tokens,
+    GREATEST(COALESCE("usage".cache_read_input_tokens, 0), 0) AS cache_read_tokens,
+    COALESCE("usage".endpoint_api_format, "usage".api_format) AS normalized_api_format,
+    COALESCE(CAST("usage".total_cost_usd AS DOUBLE PRECISION), 0) AS total_cost_usd,
+    COALESCE(CAST("usage".actual_total_cost_usd AS DOUBLE PRECISION), 0) AS actual_total_cost_usd,
+    GREATEST(COALESCE("usage".response_time_ms, 0), 0) AS response_time_ms,
+    CASE
+      WHEN "usage".status IN ('completed', 'success', 'ok', 'billed', 'settled')
+           AND ("usage".status_code IS NULL OR "usage".status_code < 400)
+      THEN 1
+      ELSE 0
+    END AS success_flag
+  FROM "usage"
+  WHERE "usage".created_at >= TO_TIMESTAMP($1::double precision)
+    AND "usage".created_at < TO_TIMESTAMP($2::double precision)
+    AND "usage".status NOT IN ('pending', 'streaming')
+    {filtered_extra_where}
+),
+normalized_usage AS (
+  SELECT
+    {group_key_expr} AS group_key,
+    {display_name_expr} AS display_name,
+    {secondary_name_expr} AS secondary_name,
+    total_tokens,
+    output_tokens,
+    cache_creation_tokens,
+    cache_creation_ephemeral_5m_tokens,
+    cache_creation_ephemeral_1h_tokens,
+    cache_read_tokens,
+    total_cost_usd,
+    actual_total_cost_usd,
+    response_time_ms,
+    success_flag,
+    CASE
+      WHEN input_tokens <= 0 THEN 0
+      WHEN cache_read_tokens <= 0 THEN input_tokens
+      WHEN split_part(lower(COALESCE(normalized_api_format, '')), ':', 1)
+           IN ('openai', 'gemini', 'google')
+      THEN GREATEST(input_tokens - cache_read_tokens, 0)
+      ELSE input_tokens
+    END AS effective_input_tokens,
+    CASE
+      WHEN split_part(lower(COALESCE(normalized_api_format, '')), ':', 1)
+           IN ('claude', 'anthropic')
+      THEN input_tokens + cache_creation_tokens + cache_read_tokens
+      WHEN split_part(lower(COALESCE(normalized_api_format, '')), ':', 1)
+           IN ('openai', 'gemini', 'google')
+      THEN (
+        CASE
+          WHEN input_tokens <= 0 THEN 0
+          WHEN cache_read_tokens <= 0 THEN input_tokens
+          WHEN split_part(lower(COALESCE(normalized_api_format, '')), ':', 1)
+               IN ('openai', 'gemini', 'google')
+          THEN GREATEST(input_tokens - cache_read_tokens, 0)
+          ELSE input_tokens
+        END
+      ) + cache_read_tokens
+      ELSE CASE
+        WHEN cache_creation_tokens > 0
+        THEN input_tokens + cache_creation_tokens + cache_read_tokens
+        ELSE input_tokens + cache_read_tokens
+      END
+    END AS total_input_context
+  FROM filtered_usage
+),
+aggregated_usage AS (
+  SELECT
+    group_key,
+    {aggregate_display_name_expr} AS display_name,
+    {aggregate_secondary_name_expr} AS secondary_name,
+    COUNT(*)::BIGINT AS request_count,
+    COALESCE(SUM(total_tokens), 0)::BIGINT AS total_tokens,
+    COALESCE(SUM(output_tokens), 0)::BIGINT AS output_tokens,
+    COALESCE(SUM(effective_input_tokens), 0)::BIGINT AS effective_input_tokens,
+    COALESCE(SUM(total_input_context), 0)::BIGINT AS total_input_context,
+    COALESCE(SUM(cache_creation_tokens), 0)::BIGINT AS cache_creation_tokens,
+    COALESCE(SUM(cache_creation_ephemeral_5m_tokens), 0)::BIGINT
+      AS cache_creation_ephemeral_5m_tokens,
+    COALESCE(SUM(cache_creation_ephemeral_1h_tokens), 0)::BIGINT
+      AS cache_creation_ephemeral_1h_tokens,
+    COALESCE(SUM(cache_read_tokens), 0)::BIGINT AS cache_read_tokens,
+    COALESCE(SUM(total_cost_usd), 0) AS total_cost_usd,
+    COALESCE(SUM(actual_total_cost_usd), 0) AS actual_total_cost_usd,
+    {avg_response_time_expr} AS avg_response_time_ms,
+    {success_count_expr} AS success_count
+  FROM normalized_usage
+  GROUP BY group_key
+)
+SELECT
+  group_key,
+  display_name,
+  secondary_name,
+  request_count,
+  total_tokens,
+  output_tokens,
+  effective_input_tokens,
+  total_input_context,
+  cache_creation_tokens,
+  cache_creation_ephemeral_5m_tokens,
+  cache_creation_ephemeral_1h_tokens,
+  cache_read_tokens,
+  total_cost_usd,
+  actual_total_cost_usd,
+  avg_response_time_ms,
+  success_count
+FROM aggregated_usage
+ORDER BY request_count DESC, group_key ASC
+LIMIT $3
+"#,
+            filtered_extra_where = fragments.filtered_extra_where,
+            group_key_expr = fragments.group_key_expr,
+            display_name_expr = fragments.display_name_expr,
+            secondary_name_expr = fragments.secondary_name_expr,
+            aggregate_display_name_expr = fragments.aggregate_display_name_expr,
+            aggregate_secondary_name_expr = fragments.aggregate_secondary_name_expr,
+            avg_response_time_expr = fragments.avg_response_time_expr,
+            success_count_expr = fragments.success_count_expr,
+        );
+
+        let mut rows = sqlx::query(&sql)
+            .bind(query.created_from_unix_secs as f64)
+            .bind(query.created_until_unix_secs as f64)
+            .bind(i64::try_from(query.limit).map_err(|_| {
+                DataLayerError::InvalidInput(format!(
+                    "invalid usage aggregation limit: {}",
+                    query.limit
+                ))
+            })?)
+            .fetch(&self.pool);
+
+        let mut items = Vec::new();
+        while let Some(row) = rows.try_next().await.map_postgres_err()? {
+            items.push(StoredUsageAuditAggregation {
+                group_key: row.try_get::<String, _>("group_key").map_postgres_err()?,
+                display_name: row
+                    .try_get::<Option<String>, _>("display_name")
+                    .map_postgres_err()?,
+                secondary_name: row
+                    .try_get::<Option<String>, _>("secondary_name")
+                    .map_postgres_err()?,
+                request_count: row
+                    .try_get::<i64, _>("request_count")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                total_tokens: row
+                    .try_get::<i64, _>("total_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                output_tokens: row
+                    .try_get::<i64, _>("output_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                effective_input_tokens: row
+                    .try_get::<i64, _>("effective_input_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                total_input_context: row
+                    .try_get::<i64, _>("total_input_context")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                cache_creation_tokens: row
+                    .try_get::<i64, _>("cache_creation_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                cache_creation_ephemeral_5m_tokens: row
+                    .try_get::<i64, _>("cache_creation_ephemeral_5m_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                cache_creation_ephemeral_1h_tokens: row
+                    .try_get::<i64, _>("cache_creation_ephemeral_1h_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                cache_read_tokens: row
+                    .try_get::<i64, _>("cache_read_tokens")
+                    .map_postgres_err()?
+                    .max(0) as u64,
+                total_cost_usd: row.try_get::<f64, _>("total_cost_usd").map_postgres_err()?,
+                actual_total_cost_usd: row
+                    .try_get::<f64, _>("actual_total_cost_usd")
+                    .map_postgres_err()?,
+                avg_response_time_ms: row
+                    .try_get::<Option<f64>, _>("avg_response_time_ms")
+                    .map_postgres_err()?,
+                success_count: row
+                    .try_get::<Option<i64>, _>("success_count")
+                    .map_postgres_err()?
+                    .map(|value| value.max(0) as u64),
+            });
+        }
+        Ok(items)
+    }
+
     pub async fn summarize_usage_daily_heatmap(
         &self,
         query: &UsageDailyHeatmapQuery,
@@ -1756,6 +2494,38 @@ impl UsageReadRepository for SqlxUsageReadRepository {
         Self::list_usage_audits(self, query).await
     }
 
+    async fn count_usage_audits(&self, query: &UsageAuditListQuery) -> Result<u64, DataLayerError> {
+        Self::count_usage_audits(self, query).await
+    }
+
+    async fn aggregate_usage_audits(
+        &self,
+        query: &UsageAuditAggregationQuery,
+    ) -> Result<Vec<StoredUsageAuditAggregation>, DataLayerError> {
+        Self::aggregate_usage_audits(self, query).await
+    }
+
+    async fn summarize_usage_audits(
+        &self,
+        query: &UsageAuditSummaryQuery,
+    ) -> Result<StoredUsageAuditSummary, DataLayerError> {
+        Self::summarize_usage_audits(self, query).await
+    }
+
+    async fn summarize_usage_time_series(
+        &self,
+        query: &UsageTimeSeriesQuery,
+    ) -> Result<Vec<StoredUsageTimeSeriesBucket>, DataLayerError> {
+        Self::summarize_usage_time_series(self, query).await
+    }
+
+    async fn summarize_usage_leaderboard(
+        &self,
+        query: &UsageLeaderboardQuery,
+    ) -> Result<Vec<StoredUsageLeaderboardSummary>, DataLayerError> {
+        Self::summarize_usage_leaderboard(self, query).await
+    }
+
     async fn list_recent_usage_audits(
         &self,
         user_id: Option<&str>,

frontend/src/api/usage.ts

@@ -284,7 +284,10 @@ export const usageApi = {
    * 获取活跃请求的状态（轻量级接口，用于轮询更新）
    * @param ids 可选，逗号分隔的请求 ID 列表
    */
-  async getActiveRequests(ids?: string[]): Promise<{
+  async getActiveRequests(
+    ids?: string[],
+    timeRange?: Pick<UsageFilters, 'start_date' | 'end_date' | 'preset' | 'timezone' | 'tz_offset_minutes'>
+  ): Promise<{
     requests: Array<{
       id: string
       status: 'pending' | 'streaming' | 'completed' | 'failed' | 'cancelled'
@@ -307,7 +310,25 @@ export const usageApi = {
       target_model?: string | null
     }>
   }> {
-    const params = ids?.length ? { ids: ids.join(',') } : {}
+    const params: Record<string, string | number> = {}
+    if (ids?.length) {
+      params.ids = ids.join(',')
+    }
+    if (timeRange?.start_date) {
+      params.start_date = timeRange.start_date
+    }
+    if (timeRange?.end_date) {
+      params.end_date = timeRange.end_date
+    }
+    if (timeRange?.preset) {
+      params.preset = timeRange.preset
+    }
+    if (timeRange?.timezone) {
+      params.timezone = timeRange.timezone
+    }
+    if (typeof timeRange?.tz_offset_minutes === 'number') {
+      params.tz_offset_minutes = timeRange.tz_offset_minutes
+    }
     const response = await apiClient.get('/api/admin/usage/active', { params })
     return response.data
   },

frontend/src/features/usage/composables/useDateRange.ts

@@ -1,15 +1,5 @@
 import type { PeriodValue, DateRangeParams } from '../types'
 
-/**
- * 格式化日期为 ISO 格式（不带毫秒，兼容 FastAPI datetime 解析）
- */
-function formatDateForApi(date: Date): string {
-  const year = date.getFullYear()
-  const month = String(date.getMonth() + 1).padStart(2, '0')
-  const day = String(date.getDate()).padStart(2, '0')
-  return `${year}-${month}-${day}`
-}
-
 function getTimezoneParams() {
   const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
   const tz_offset_minutes = -new Date().getTimezoneOffset()
@@ -20,37 +10,19 @@ function getTimezoneParams() {
  * 根据时间段值计算日期范围
  */
 export function getDateRangeFromPeriod(period: PeriodValue): DateRangeParams {
-  const now = new Date()
-  let startDate: Date
-  let endDate = new Date(now)
-
   switch (period) {
     case 'today':
-      startDate = new Date(now.getFullYear(), now.getMonth(), now.getDate())
-      break
     case 'yesterday':
-      startDate = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1)
-      endDate = new Date(now.getFullYear(), now.getMonth(), now.getDate())
-      break
     case 'last7days':
-      startDate = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)
-      break
     case 'last30days':
-      startDate = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000)
-      break
     case 'last90days':
-      startDate = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1000)
-      break
-    default:
-      return {} // 返回空对象表示不过滤时间
-  }
-
       return {
-    start_date: formatDateForApi(startDate),
-    end_date: formatDateForApi(endDate),
         preset: period,
         ...getTimezoneParams()
       }
+    default:
+      return {} // 返回空对象表示不过滤时间
+  }
 }
 
 /**

frontend/src/views/shared/Usage.vue

@@ -347,7 +347,7 @@ const discoveredActiveRequestIds = new Set<string>()
 
 async function loadActiveRequestUpdates(ids?: string[]) {
   if (isAdminPage.value) {
-    return usageApi.getActiveRequests(ids)
+    return usageApi.getActiveRequests(ids, timeRange.value)
   }
   const idsParam = ids?.length ? ids.join(',') : undefined
   return meApi.getActiveRequests(idsParam)