sentryagent-idp/docs/developers/guides/use-analytics-dashboard.md

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.

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

Response:

{
  "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.

# 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.

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

Response:

{
  "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.

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

Response:

{
  "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.