Guardian Health LogoGuardian Health
Safe AI Workbench Developer Docs

Analytics API

Access usage analytics, trends, and reporting data for your organization

Overview

The Analytics API provides comprehensive usage metrics, cost tracking, and insights into AI assistant usage across your organization. Track token consumption, model usage, policy enforcement, and user activity.

Note: All analytics endpoints require authentication and are scoped to the user's organization. Site admins can access cross-organization analytics.

Dashboard Statistics

GET /api/admin/analytics/stats

Returns high-level dashboard statistics for the current billing period.

Request Headers

Authorization: Bearer YOUR_JWT_TOKEN

Response

{
  "totalRequests": 1245,
  "totalTokens": 385420,
  "totalCost": 12.45,
  "uniqueUsers": 23,
  "averageLatency": 1850,
  "blockedRequests": 12,
  "phiDetections": 45,
  "previousPeriod": {
    "totalRequests": 1100,
    "totalTokens": 340000,
    "totalCost": 11.20,
    "uniqueUsers": 21
  },
  "trends": {
    "requests": "up",
    "cost": "up",
    "tokens": "stable"
  }
}

Response Fields

totalRequests— Total API requests in current period
totalTokens— Combined input + completion tokens
totalCost— Total cost in USD
blockedRequests— Requests blocked by policies
phiDetections— Total PHI entities detected

Usage Trends

GET /api/admin/analytics/trends

Returns time-series data for usage trends over the past 30 days.

Query Parameters

startDate— Optional start date (ISO 8601)
endDate— Optional end date (ISO 8601)

Response

{
  "labels": [
    "2025-01-01", "2025-01-02", "2025-01-03"
  ],
  "datasets": {
    "requests": [45, 52, 48],
    "cost": [1.20, 1.35, 1.28],
    "inputTokens": [12000, 14000, 13500],
    "completionTokens": [8000, 9200, 8800]
  }
}

Task Breakdown

GET /api/admin/analytics/tasks

Returns usage statistics broken down by AI task type.

Response

[
  {
    "taskId": "draft-email",
    "taskName": "Draft Email",
    "category": "HR & Communications",
    "usageCount": 156,
    "tokenCount": 42000,
    "avgLatency": 1800,
    "cost": 3.20
  },
  {
    "taskId": "summarize-document",
    "taskName": "Summarize Document",
    "category": "Operations & Finance",
    "usageCount": 89,
    "tokenCount": 28000,
    "cost": 2.10
  }
]

Model Breakdown

GET /api/admin/analytics/models

Returns usage statistics broken down by AI model.

Response

[
  {
    "model": "gpt-4-turbo",
    "requests": 845,
    "inputTokens": 245000,
    "completionTokens": 180000,
    "totalTokens": 425000,
    "cost": 8.50,
    "avgLatency": 1850
  },
  {
    "model": "gpt-3.5-turbo",
    "requests": 400,
    "inputTokens": 98000,
    "completionTokens": 72000,
    "totalTokens": 170000,
    "cost": 0.85,
    "avgLatency": 1200
  }
]

Top Users

GET /api/admin/analytics/users/top

Returns the top users by request volume, tokens, or cost.

Query Parameters

limit— Number of users to return (default: 10)
sortBy— Sort by: requests, tokens, cost (default: requests)

Response

[
  {
    "userId": "user-uuid-1",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "requests": 245,
    "tokens": 85000,
    "cost": 4.25
  },
  {
    "userId": "user-uuid-2",
    "email": "jane.smith@example.com",
    "name": "Jane Smith",
    "requests": 189,
    "tokens": 62000,
    "cost": 3.10
  }
]

Policy Statistics

GET /api/admin/analytics/policies

Returns policy enforcement statistics including blocks, warnings, and PHI detections.

Response

{
  "totalEvaluations": 1245,
  "blocks": 12,
  "warnings": 34,
  "redactions": 28,
  "phiDetections": 45,
  "topPolicies": [
    {
      "policyId": "policy-uuid-1",
      "policyName": "Default PHI Detection",
      "triggers": 45,
      "blocks": 8,
      "warnings": 25,
      "redactions": 12
    }
  ]
}

Error Codes

401 Unauthorized

Missing or invalid authentication token

403 Forbidden

Insufficient permissions (requires admin/manager role)

400 Bad Request

Invalid query parameters (e.g., invalid date format)