# Analytics

> Understand model usage, settled cost, Resource reliability, custom events, live projections, and durable historical exports.

Analytics answers historical and aggregate questions about Runs, models, Tools, Resource operations, Channels, deployments, Credentials, and custom product events. The Console dashboard uses a bounded recent projection for model calls, tokens, cache use, latency, spend, Agent activity, and Resource reliability.

Analytics is not authoritative live workflow state. A Session exposes current status, waits, controls, journals, and ledger facts. Use a Session’s `/workflow` endpoint when an operator needs authoritative liveness; use analytics for cross-workflow trends, investigation, cost, and export.

## Data guarantees {#data-guarantees}

Audit-critical and billable transitions are durably recorded at the service that owns the underlying fact. Their canonical event IDs are retried into the shared historical archive and deduplicated when queried. Authentication state remains authoritative in Auth, balances and debits in Billing, and Run state in the owning Session; analytics is their centralized projection, not a replacement authority.

Ordinary HTTP request telemetry is best-effort. Recent live views are operational and may contain at-least-once duplicates or omit a point. Historical queries and exports use the durable archive and deduplicate canonical event IDs; use those surfaces for exact cost, margin, billing-evidence, and audit analysis.

## Data paths {#data-paths}

| Need | Interface |
| --- | --- |
| Recent dashboard and activity | Console or `POST .../analytics/dashboard` and `/live` |
| Simple recent summary | `GET .../analytics/summary` |
| Aggregate or raw historical query | `POST .../analytics/query` |
| Bounded durable artifact | `POST .../analytics/exports`, then `GET .../exports/:ref` |
| Product-specific event | `analyticsEvent()` plus runtime `emit()` |
| Exact current Run state | Session `/workflow`, Run detail, and journal routes |

## Choose an interface {#choose-an-interface}

| Interface | Use it for |
| --- | --- |
| Console | Visual exploration of recent usage, cost, activity, and reliability |
| [SDK](/docs/analytics/sdk.md) | Declaring bounded custom events in runtime code |
| [CLI](/docs/analytics/cli.md) | Repeatable recent queries, historical analysis, and exports |
| [Platform API](/docs/api/analytics-and-data.md) | Product dashboards, data workflows, and artifact retrieval |

Use [Instrument custom analytics](/docs/analytics/instrument.md) to add a typed event. Use [Query and export analytics](/docs/analytics/query-and-export.md) for time windows, filters, grouping, raw detail, and artifacts.