Analytics API

Aggregate, time-bucketed views over the same source data as the Logs API — but rolled up for dashboards, alerting, and continuous monitoring instead of per-record forensic detail.

Authentication: Authorization: Bearer <session_token | api_key> with logs:read (or mcp:read / nhi:read for the dimensions below).

Endpoints

Guardian governance metrics

Method	Path	Purpose
`GET`	`/v1/analytics/governance/summary`	Aggregate verdict counts and rates across Guardians
`GET`	`/v1/analytics/governance/timeseries`	Bucketed timeseries for verdicts, latency, and corrections
`GET`	`/v1/analytics/governance/by-guardian`	Per-Guardian rollup for the period

MCP tool-call analytics

Method	Path	Purpose
`GET`	`/v1/mcp/analytics/summary`	Tool-call counts by verdict and tool
`GET`	`/v1/mcp/analytics/tools`	Per-tool aggregates
`POST`	`/v1/mcp/analytics/rollup`	Trigger an on-demand rollup of a time window
`GET`	`/v1/mcp/analytics/sessions`	Sessions list with verdict mix
`GET`	`/v1/mcp/analytics/sessions/{sessionId}`	Per-session detail
`GET`	`/v1/mcp/analytics/config-audit`	Configuration changes that affected analytics

For the MCP REST + JSON-RPC surface itself (not analytics), see the MCP Gateway.

NHI risk and observability

Method	Path	Purpose
`GET`	`/v1/analytics/nhi-risk`	Aggregate risk score by NHI
`GET`	`/v1/analytics/nhi-observability`	Observability rollup for autonomous workloads
`GET`	`/v1/analytics/nhi-risk-assessment/{id}`	Detailed risk assessment for one NHI
`GET`	`/v1/analytics/nhi-risk-assessment/{id}/history`	Historical risk timeline
`POST`	`/v1/analytics/nhi-risk/detect-anomalies`	Run anomaly detection over a window
`GET`	`/v1/analytics/nhi-anomalies`	Open anomalies
`POST`	`/v1/analytics/nhi-anomalies/{id}/ack`	Acknowledge an anomaly
`GET`	`/v1/analytics/nhi-posture`	Composite governance posture score by NHI

For full NHI lifecycle and federation, see Identities.

Common query parameters

Most analytics endpoints accept the same time-window and grouping parameters:

Param	Type	Default	Description
`from`	RFC 3339	now − 24h	Window start (inclusive)
`to`	RFC 3339	now	Window end (exclusive)
`bucket`	`string`	`1h`	Aggregation granularity: `1m`, `5m`, `15m`, `1h`, `1d`
`guardian_id`	`string`	—	Filter to one Guardian
`environment`	`string`	—	`live`, `test`, `dev`
`tag`	`string`	—	Organizational tag

GET /v1/analytics/governance/summary

Aggregate verdict counts for a window.

{
  "from": "2026-04-30T00:00:00Z",
  "to": "2026-05-01T00:00:00Z",
  "totals": {
    "requests": 14302,
    "passed": 12907,
    "corrected": 1208,
    "blocked": 87,
    "errors": 100
  },
  "rates": {
    "pass_rate": 0.9024,
    "correction_rate": 0.0845,
    "block_rate": 0.0061
  },
  "latency_p50_ms": 122,
  "latency_p95_ms": 187,
  "latency_p99_ms": 244
}

GET /v1/analytics/governance/timeseries

Bucketed timeseries for the requested window.

Param	Default	Description
`metric`	`verdicts`	`verdicts`, `latency`, `corrections`, `violations`
`bucket`	`1h`	Aggregation granularity

{
  "metric": "verdicts",
  "bucket": "1h",
  "from": "2026-05-01T00:00:00Z",
  "to": "2026-05-02T00:00:00Z",
  "series": [
    {
      "timestamp": "2026-05-01T00:00:00Z",
      "passed": 540, "corrected": 51, "blocked": 4, "errors": 2
    },
    {
      "timestamp": "2026-05-01T01:00:00Z",
      "passed": 612, "corrected": 47, "blocked": 6, "errors": 1
    }
  ]
}

GET /v1/analytics/governance/by-guardian

Per-Guardian rollup for the period.

{
  "from": "2026-04-30T00:00:00Z",
  "to": "2026-05-01T00:00:00Z",
  "data": [
    {
      "guardian_id": "gov_01JF8R3M3X4N5Q6T7V8W9Y0Z1A",
      "guardian_name": "PII-Redactor",
      "requests": 8201,
      "passed": 7411,
      "corrected": 720,
      "blocked": 60,
      "avg_latency_ms": 142,
      "top_violation_types": [
        { "type": "pii_exposure", "count": 720 },
        { "type": "credential_leak", "count": 60 }
      ]
    }
  ]
}

MCP analytics

GET /v1/mcp/analytics/summary

{
  "from": "2026-04-30T00:00:00Z",
  "to": "2026-05-01T00:00:00Z",
  "totals": {
    "tool_calls": 4123,
    "passed": 3812,
    "corrected": 264,
    "blocked": 47
  },
  "by_verdict": { "passed": 0.925, "corrected": 0.064, "blocked": 0.011 },
  "top_tools": [
    { "tool": "stripe.create_refund", "calls": 412, "block_rate": 0.041 },
    { "tool": "postgres.query",       "calls": 1840, "block_rate": 0.005 }
  ]
}

POST /v1/mcp/analytics/rollup

Trigger an on-demand rollup of a time window. Returns 202 Accepted.

{ "from": "2026-05-01T00:00:00Z", "to": "2026-05-01T23:59:59Z" }

{ "rollup_id": "rlp_01JF8RML1A2B3C4D5E6F7G8H9I", "status": "queued" }

NHI analytics

GET /v1/analytics/nhi-risk

Aggregate risk-score view, one row per NHI.

{
  "from": "2026-04-24T00:00:00Z",
  "to":   "2026-05-01T00:00:00Z",
  "data": [
    {
      "nhi_id": "nhi_01JF8RNHI1A2B3C4D5E6F7G8H9",
      "nhi_label": "ci-runner-prod",
      "tier": 2,
      "risk_score": 0.21,
      "risk_signals": ["spend_burst:p99", "tool_attempt:denied:3"],
      "last_seen_at": "2026-05-01T11:42:08Z"
    }
  ]
}

GET /v1/analytics/nhi-posture

Composite governance posture score by NHI — combines risk score, tier compliance, federation status, and Guardian assignment coverage.

{
  "data": [
    {
      "nhi_id": "nhi_01JF8RNHI1A2B3C4D5E6F7G8H9",
      "posture_score": 0.86,
      "components": {
        "guardian_coverage": 1.0,
        "tier_compliance":   0.95,
        "federation_status": 0.80,
        "anomaly_count_7d":  2
      }
    }
  ]
}

For the full NHI surface — federation registry, tier transitions, Guardian binding — see Identities.

Anomalies

POST /v1/analytics/nhi-risk/detect-anomalies

Run anomaly detection over a window. Returns 202 Accepted with a job ID.

{ "from": "2026-04-30T00:00:00Z", "to": "2026-05-01T00:00:00Z" }

{ "job_id": "job_01JF8RAJ1A2B3C4D5E6F7G8H9I", "status": "queued" }

GET /v1/analytics/nhi-anomalies

{
  "data": [
    {
      "anomaly_id": "anom_01JF8RAN1A2B3C4D5E6F7G8H9I",
      "nhi_id": "nhi_01JF8RNHI1A2B3C4D5E6F7G8H9",
      "type": "spend_burst",
      "severity": "high",
      "detected_at": "2026-05-01T08:14:00Z",
      "evidence": { "p99_spend_usd_24h": 12.40, "rolling_baseline": 0.83 },
      "status": "open"
    }
  ],
  "page": { "next_cursor": null, "has_more": false }
}

POST /v1/analytics/nhi-anomalies/{id}/ack

Acknowledge an anomaly with an optional note. Returns the updated anomaly with status: "acknowledged".

{ "note": "Reviewed by SRE — known release event." }

Errors

HTTP	`error.code`	Cause
`400`	`validation_error`	Malformed `from`/`to`, unknown `metric` or `bucket`
`401`	`unauthenticated`	Missing or invalid credential
`403`	`forbidden`	Caller lacks `logs:read` / `mcp:read` / `nhi:read`
`404`	`not_found`	Anomaly, NHI, rollup, or session not found
`422`	`unprocessable_entity`	Window too large for requested bucket
`429`	`rate_limited`	Per-organization rate limit exceeded

Best practices

Cache aggregates. Analytics endpoints serve pre-rolled-up data — re-querying the same window in a tight loop wastes quota.
Use the right bucket. 1m over a 30-day window will be rejected. Pair small buckets with short windows.
Pull raw logs only when needed. For drill-down dashboards, compose with the Logs API.

Next steps

Forensic per-record data → Logs API
Govern an MCP tool call → MCP Gateway
Manage autonomous identities → Identities
Long-form board-ready reports → Reports API

Endpoints​

Guardian governance metrics​

MCP tool-call analytics​

NHI risk and observability​

Common query parameters​

GET /v1/analytics/governance/summary​

GET /v1/analytics/governance/timeseries​

GET /v1/analytics/governance/by-guardian​

MCP analytics​

GET /v1/mcp/analytics/summary​

POST /v1/mcp/analytics/rollup​

NHI analytics​

GET /v1/analytics/nhi-risk​

GET /v1/analytics/nhi-posture​

Anomalies​

POST /v1/analytics/nhi-risk/detect-anomalies​

GET /v1/analytics/nhi-anomalies​

POST /v1/analytics/nhi-anomalies/{id}/ack​

Errors​

Best practices​

Next steps​