AI Analytics

Retrieve usage, cost, and performance analytics for AI models managed by the Strongly AI Gateway. All analytics endpoints are read-only and support date range filtering.

---

GET /api/v1/ai/analytics/usage

Get usage statistics

Returns aggregated usage statistics including request counts and token consumption, optionally broken down by time period.

Scope: ai-gateway:read

Parameters:

Name	In	Type	Required	Description
startDate	query	string	No	Start of date range (ISO 8601). Defaults to 30 days ago
endDate	query	string	No	End of date range (ISO 8601). Defaults to now
modelId	query	string	No	Filter by specific model ID
provider	query	string	No	Filter by provider: openai, anthropic, google, etc.
granularity	query	string	No	Time granularity: hour, day, week, month. Default: day

Response: 200 OK

{
  "data": {
    "totalRequests": 145230,
    "totalTokens": 28500000,
    "promptTokens": 18200000,
    "completionTokens": 10300000,
    "period": "custom",
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-02-07T23:59:59.000Z",
    "modelId": null,
    "provider": null,
    "granularity": "day",
    "breakdown": [
      {
        "date": "2025-02-06T00:00:00.000Z",
        "requests": 4200,
        "totalTokens": 820000,
        "promptTokens": 520000,
        "completionTokens": 300000
      },
      {
        "date": "2025-02-07T00:00:00.000Z",
        "requests": 3800,
        "totalTokens": 750000,
        "promptTokens": 480000,
        "completionTokens": 270000
      }
    ]
  },
  "meta": { "requestId": "req_abc123" }
}

---

GET /api/v1/ai/analytics/costs

Get cost breakdown

Returns cost data broken down by model, provider, or time period. Costs are calculated based on provider pricing and token usage.

Scope: ai-gateway:read

Parameters:

Name	In	Type	Required	Description
startDate	query	string	No	Start of date range (ISO 8601). Defaults to 30 days ago
endDate	query	string	No	End of date range (ISO 8601). Defaults to now
modelId	query	string	No	Filter by specific model ID
provider	query	string	No	Filter by provider
groupBy	query	string	No	Group results by: model, provider, day, week, month. Default: model

Response: 200 OK

{
  "data": {
    "totalCost": 1245.67,
    "currency": "USD",
    "period": "custom",
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-02-07T23:59:59.000Z",
    "modelId": null,
    "provider": null,
    "groupBy": "model",
    "byModel": [
      {
        "modelId": "model_abc123",
        "modelName": "GPT-4 Production",
        "provider": "openai",
        "cost": 890.45,
        "requests": 52000,
        "totalTokens": 15000000
      },
      {
        "modelId": "model_def456",
        "modelName": "Claude 3 Opus",
        "provider": "anthropic",
        "cost": 355.22,
        "requests": 28000,
        "totalTokens": 9500000
      }
    ],
    "byProvider": [
      {
        "provider": "openai",
        "cost": 890.45,
        "requests": 52000,
        "totalTokens": 15000000
      },
      {
        "provider": "anthropic",
        "cost": 355.22,
        "requests": 28000,
        "totalTokens": 9500000
      }
    ]
  },
  "meta": { "requestId": "req_abc123" }
}

---

GET /api/v1/ai/analytics/performance

Get performance metrics

Returns latency, error rate, and throughput statistics for AI inference requests.

Scope: ai-gateway:read

Parameters:

Name	In	Type	Required	Description
startDate	query	string	No	Start of date range (ISO 8601). Defaults to 30 days ago
endDate	query	string	No	End of date range (ISO 8601). Defaults to now
modelId	query	string	No	Filter by specific model ID
provider	query	string	No	Filter by provider

Response: 200 OK

{
  "data": {
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-02-07T23:59:59.000Z",
    "modelId": null,
    "provider": null,
    "avgLatencyMs": 485,
    "p50LatencyMs": 320,
    "p95LatencyMs": 1200,
    "p99LatencyMs": 2800,
    "errorRate": 0.015,
    "throughput": 45.2
  },
  "meta": { "requestId": "req_abc123" }
}

Field	Type	Description
avgLatencyMs	number	Mean request latency in milliseconds
p50LatencyMs	number	50th percentile (median) latency
p95LatencyMs	number	95th percentile latency
p99LatencyMs	number	99th percentile latency
errorRate	number	Fraction of requests that failed (0.0 - 1.0)
throughput	number	Average requests per minute during the period

---

GET /api/v1/ai/analytics/time-series

Get time-series data

Returns time-series data points for a specific metric, suitable for charting and trend analysis.

Scope: ai-gateway:read

Parameters:

Name	In	Type	Required	Description
startDate	query	string	No	Start of date range (ISO 8601). Defaults to 7 days ago
endDate	query	string	No	End of date range (ISO 8601). Defaults to now
modelId	query	string	No	Filter by specific model ID
metric	query	string	No	Metric to chart: requests, tokens, latency, errors, cost. Default: requests
granularity	query	string	No	Time granularity: hour, day, week, month. Default: hour
provider	query	string	No	Filter by provider

Response: 200 OK

{
  "data": {
    "metric": "requests",
    "granularity": "hour",
    "startDate": "2025-02-06T00:00:00.000Z",
    "endDate": "2025-02-07T23:59:59.000Z",
    "modelId": null,
    "provider": null,
    "points": [
      {
        "timestamp": "2025-02-06T00:00:00.000Z",
        "value": 185
      },
      {
        "timestamp": "2025-02-06T01:00:00.000Z",
        "value": 142
      },
      {
        "timestamp": "2025-02-06T02:00:00.000Z",
        "value": 98
      }
    ]
  },
  "meta": { "requestId": "req_abc123" }
}

---

GET /api/v1/ai/analytics/providers

Get per-provider statistics

Returns aggregated statistics grouped by AI provider, useful for comparing provider performance and costs side by side.

Scope: ai-gateway:read

Parameters:

Name	In	Type	Required	Description
startDate	query	string	No	Start of date range (ISO 8601). Defaults to 30 days ago
endDate	query	string	No	End of date range (ISO 8601). Defaults to now

Response: 200 OK

{
  "data": {
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-02-07T23:59:59.000Z",
    "providers": [
      {
        "provider": "openai",
        "models": 5,
        "totalRequests": 82000,
        "totalTokens": 18500000,
        "totalCost": 890.45,
        "avgLatencyMs": 420,
        "errorRate": 0.012
      },
      {
        "provider": "anthropic",
        "models": 3,
        "totalRequests": 45000,
        "totalTokens": 12000000,
        "totalCost": 355.22,
        "avgLatencyMs": 550,
        "errorRate": 0.008
      },
      {
        "provider": "google",
        "models": 2,
        "totalRequests": 18230,
        "totalTokens": 4200000,
        "totalCost": 125.80,
        "avgLatencyMs": 380,
        "errorRate": 0.018
      }
    ]
  },
  "meta": { "requestId": "req_abc123" }
}

---

Response Models Reference

UsageStats

Field	Type	Description
totalRequests	integer	Total number of inference requests
totalTokens	integer	Total tokens consumed (prompt + completion)
promptTokens	integer	Total input/prompt tokens
completionTokens	integer	Total output/completion tokens
period	string	Time period label (custom, last-7d, last-30d)
startDate	string	Period start (ISO 8601)
endDate	string	Period end (ISO 8601)
modelId	string	Applied model filter, or null
provider	string	Applied provider filter, or null
granularity	string	Time bucket size: hour, day, week, month
breakdown	array	Time-bucketed usage data points

CostBreakdown

Field	Type	Description
totalCost	number	Total cost in the specified currency
currency	string	Currency code (e.g., USD)
period	string	Time period label
startDate	string	Period start (ISO 8601)
endDate	string	Period end (ISO 8601)
modelId	string	Applied model filter, or null
provider	string	Applied provider filter, or null
groupBy	string	Grouping dimension: model, provider, day, week, month
byModel	array	Cost breakdown per model
byProvider	array	Cost breakdown per provider

PerformanceStats

Field	Type	Description
startDate	string	Period start (ISO 8601)
endDate	string	Period end (ISO 8601)
modelId	string	Applied model filter, or null
provider	string	Applied provider filter, or null
avgLatencyMs	number	Mean request latency in milliseconds
p50LatencyMs	number	50th percentile (median) latency in milliseconds
p95LatencyMs	number	95th percentile latency in milliseconds
p99LatencyMs	number	99th percentile latency in milliseconds
errorRate	number	Fraction of requests that returned errors (0.0 - 1.0)
throughput	number	Average requests per minute