# Use the Analytics Dashboard

This guide explains how to query the three analytics endpoints to understand your organization's
token usage and agent activity patterns.

All analytics endpoints require Bearer token authentication and are scoped to the organization
embedded in your token.

---

## Prerequisites

- A running AgentIdP instance
- A valid Bearer token with `organization_id` in its claims
- At least one agent registered and some token issuance activity

---

## Token issuance trend

`GET /api/v1/analytics/tokens`

Returns daily token issuance counts for the past N days (default 30, max 90). Use this to
track usage growth, identify traffic spikes, and plan capacity.

```bash
curl -s "http://localhost:3000/api/v1/analytics/tokens?days=30" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

Response:

```json
{
  "tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
  "days": 30,
  "data": [
    { "date": "2026-03-06", "count": 142 },
    { "date": "2026-03-07", "count": 198 },
    { "date": "2026-03-08", "count": 0 }
  ]
}
```

**Interpreting the data**: Each item in `data` is one calendar day (UTC) with the number of
tokens issued on that day. Days with zero issuance are included with `count: 0`. The array
is ordered chronologically, oldest first.

**Using it**: Compare day-over-day counts to identify growth or anomalies. A sudden spike in
`count` may indicate an agent retry loop or a credential leak. Zero-count days during expected
operation may indicate a deployment issue.

**Query parameter**: `days` — positive integer, max 90. Returns `400 VALIDATION_ERROR` if
exceeded.

```bash
# Last 7 days
curl -s "http://localhost:3000/api/v1/analytics/tokens?days=7" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Last 90 days (maximum)
curl -s "http://localhost:3000/api/v1/analytics/tokens?days=90" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

---

## Agent activity heatmap

`GET /api/v1/analytics/agents/activity`

Returns request counts grouped by day-of-week (0 = Sunday, 6 = Saturday) and hour (0–23, UTC).
Use this to identify peak usage windows for capacity planning and rate limit tuning.

```bash
curl -s "http://localhost:3000/api/v1/analytics/agents/activity" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

Response:

```json
{
  "tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
  "data": [
    { "dow": 1, "hour": 9, "count": 54 },
    { "dow": 1, "hour": 10, "count": 87 },
    { "dow": 3, "hour": 14, "count": 201 }
  ]
}
```

**Interpreting the data**: `dow` is 0 (Sunday) through 6 (Saturday). `hour` is 0–23 UTC.
Only non-zero cells are returned — missing combinations had zero activity. Sort by `count`
descending to find your peak windows.

**Using it**: If most activity is on weekday mornings UTC, ensure your rate limit headroom
covers that window. If weekend activity is unexpectedly high, investigate which agents are
active.

---

## Per-agent usage summary

`GET /api/v1/analytics/agents`

Returns token issuance counts per agent for the current calendar month (UTC). Use this to
identify your most active agents and check if any single agent is consuming a
disproportionate share of your monthly token budget.

```bash
curl -s "http://localhost:3000/api/v1/analytics/agents" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

Response:

```json
{
  "tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
  "month": "2026-04",
  "data": [
    { "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tokenCount": 312 },
    { "agentId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "tokenCount": 87 }
  ]
}
```

**Interpreting the data**: Each item shows an agent UUID and the number of tokens it has
issued this month. The response covers the full current calendar month from day 1 to now.
It resets on the first day of each month.

**Using it**: Cross-reference `agentId` values against `GET /api/v1/agents` to identify which
agents by name. If one agent accounts for >80% of usage, investigate whether it is token
caching correctly or requesting tokens unnecessarily.