> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Usage analytics and reporting for agents and organizations.

# Analytics

Analytics endpoints provide usage metrics, cost tracking, and trend analysis for agents across your organization.

<Note>
  All API requests require a valid JWT token in the `Authorization: Bearer <token>` header. The API Gateway decodes the JWT and forwards auth context (`user-id`, `organization-id`, `user-email`, `x-platform-role`, `x-org-role`) as headers to downstream services.
</Note>

## Overview Metrics

<ParamField method="GET" path="/api/analytics/overview" />

Get high-level usage metrics with trend comparisons against the previous period.

### Query Parameters

<ParamField query="organizationId" type="string" required>
  Organization UUID.
</ParamField>

<ParamField query="startDate" type="string" required>
  Start of the reporting period (ISO 8601 date string).
</ParamField>

<ParamField query="endDate" type="string" required>
  End of the reporting period (ISO 8601 date string).
</ParamField>

<ParamField query="botId" type="string">
  Filter to a specific agent UUID.
</ParamField>

<ParamField query="model" type="string">
  Filter to a specific model ID.
</ParamField>

### Response (200)

Returns current period metrics with trend indicators compared to the equivalent previous period:

<ResponseField name="totalConversations" type="object">
  <Expandable title="Metric with trend">
    <ResponseField name="value" type="number">Count for current period.</ResponseField>
    <ResponseField name="trend" type="string">`up`, `down`, or `stable`.</ResponseField>
    <ResponseField name="change" type="number">Percentage change from previous period.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalMessages" type="object">Message count with trend.</ResponseField>
<ResponseField name="totalTokens" type="object">Token usage with trend.</ResponseField>
<ResponseField name="totalCost" type="object">Cost in USD with trend.</ResponseField>
<ResponseField name="averageResponseTime" type="object">Response time in ms with trend.</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://your-domain.com/api/analytics/overview?\
  organizationId=ORG_UUID&\
  startDate=2026-03-01T00:00:00Z&\
  endDate=2026-04-01T00:00:00Z" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    organizationId: orgId,
    startDate: "2026-03-01T00:00:00Z",
    endDate: "2026-04-01T00:00:00Z",
  });

  const response = await fetch(
    `https://your-domain.com/api/analytics/overview?${params}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );

  const data = await response.json();
  ```
</CodeGroup>

***

## Daily Breakdown

<ParamField method="GET" path="/api/analytics/daily" />

Get day-by-day usage breakdown for charting.

### Query Parameters

Same as [Overview Metrics](#overview-metrics).

### Response (200)

Returns an array of daily data points with conversation counts, message counts, token usage, and cost for each day.

***

## Model Usage

<ParamField method="GET" path="/api/analytics/models" />

Get usage breakdown by AI model, showing which models are used most.

### Query Parameters

Same as [Overview Metrics](#overview-metrics).

### Response (200)

Returns per-model aggregates including message count, token usage, and cost.

***

## Agent Usage

<ParamField method="GET" path="/api/analytics/bots" />

Get usage breakdown by agent.

### Query Parameters

Same as [Overview Metrics](#overview-metrics).

### Response (200)

Returns per-agent aggregates including conversation count, message count, and cost.

***

## Realtime Metrics

<ParamField method="GET" path="/api/analytics/realtime" />

Get recent activity metrics for live dashboards.

### Query Parameters

<ParamField query="organizationId" type="string" required>
  Organization UUID.
</ParamField>

<ParamField query="since" type="string">
  ISO 8601 timestamp. Only return activity after this time. Defaults to last 15 minutes.
</ParamField>

### Response (200)

Returns recent conversation and message counts, active users, and current response times.