# AgentAnalyticsController

**Kind:** Controller

**Source:** [`atloria-monorepo/apps/api/src/events/agent-analytics.controller.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/events/agent-analytics.controller.ts#L12)

Agent-native analytics — "who/what AI is reading your docs". Authed, org-scoped
read model over the agent_read events the public agent surfaces record. Guard/scope
pattern mirrors ManualsInsightsController.

`AgentAnalyticsController` exposes authenticated, organization-scoped analytics for understanding which AI agents are reading documentation. It queries the read model built from `agent_read` events recorded by public agent-facing surfaces, following the same guard and scoping conventions as `ManualsInsightsController`.

## Diagram

```mermaid
graph LR
  A[Public agent surfaces] -->|records agent_read events| B[Events / Read Model]
  B --> C[AgentAnalyticsController]
  D[Authenticated user] -->|org-scoped request| C
  C --> E[Organization analytics response]
```

## Usage

```ts
// The authenticated session determines the active organization scope.
// Do not pass or trust an organization ID supplied by the client.

const response = await fetch("/agent-analytics", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json",
  },
});

if (!response.ok) {
  throw new Error("Unable to load agent analytics");
}

const analytics = await response.json();

console.log("AI documentation reads:", analytics);
```

## AI Coding Instructions

- Apply the same authentication guards and organization-scoping pattern used by `ManualsInsightsController`.
- Treat `agent_read` events and their derived read model as the source of truth; avoid querying public-agent request paths directly for analytics.
- Derive the organization from the authenticated request context rather than accepting a client-provided organization identifier.
- Keep this controller read-only and delegate aggregation/query logic to the appropriate analytics or event read-model service.
- Ensure analytics responses cannot expose event data belonging to another organization.

## Relationships

- MODULE_DECLARES → `traffic`
- MODULE_DECLARES → `actions`
- DEPENDS_ON → `AgentAnalyticsService`

## Referenced By

- `EventsModule` (MODULE_DECLARES)