Intelligence Endpoints

Intelligence endpoints expose the Prism API’s operational signals: throttle impact, model rightsizing recommendations, and sub-session boundary review. All endpoints are scoped to the authenticated organization and developer.

Throttle

GET /v1/intelligence/throttle

Rate-limiting events, latency spikes, and service-outage detection for the authenticated developer, with an estimated-time-lost summary and mitigation recommendations.

GET /v1/intelligence/throttle?from=2024-01-01T00:00:00Z&to=2024-01-07T00:00:00Z
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
`from`	ISO8601	—	Start time
`to`	ISO8601	—	End time
`tz_offset`	integer	`0`	Timezone offset in minutes east of UTC

Response (camelCase):

{
  "isPartial": false,
  "events": [
    {
      "detector": "service_outage",
      "timestamp": "2024-01-03T14:20:00Z",
      "sessionId": "…",
      "details": "…",
      "estimatedDelaySecs": 180.0,
      "confidence": "confirmed",
      "incidentName": "Elevated API errors",
      "incidentUrl": "https://status.anthropic.com/…"
    }
  ],
  "summary": {
    "totalEvents": 3,
    "estimatedHoursLost": 0.4,
    "byDetector": [{ "detector": "service_outage", "count": 1 }],
    "totalApiRequests": 120
  },
  "recommendations": [{ "priority": "high", "action": "…", "estimatedSavingsHours": 0.3 }]
}

isPartial is always false on this personal endpoint — a budget trim on the narrow personal window is treated as a real failure and errors instead of under-reporting. confidence, incidentName, and incidentUrl appear only on service_outage events.

GET /v1/intelligence/throttle/team

Team-scoped variant of the throttle report. Requires a team_id; the caller’s team membership is verified server-side and the client-sent team_id is never trusted beyond that check.

GET /v1/intelligence/throttle/team?team_id=<uuid>&from=2024-01-01T00:00:00Z
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
`team_id`	UUID	— (required)	Team to aggregate
`from`	ISO8601	—	Start time
`to`	ISO8601	—	End time
`tz_offset`	integer	`0`	Timezone offset in minutes east of UTC

Returns the same ThrottleImpactResponse shape as the personal endpoint. Unlike the personal endpoint, the team read can set isPartial: true when a bounded file/byte read budget drops telemetry — the counts then cover less than the requested range.

Rightsizing

GET /v1/intelligence/rightsizing

Model and tier usage summaries computed directly from stored usage (no background worker).

GET /v1/intelligence/rightsizing?from=2024-01-01T00:00:00Z&to=2024-01-31T00:00:00Z
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
`from`	ISO8601	90 days ago	Start time
`to`	ISO8601	now	End time

Response (camelCase):

{
  "recommendations": [],
  "modelUsage": [
    {
      "model": "claude-sonnet-4",
      "requestCount": 420,
      "avgInputTokens": 1800.0,
      "avgOutputTokens": 640.0,
      "avgCacheReadTokens": 9200.0,
      "avgCacheCreationTokens": 210.0,
      "avgTotalTokens": 11850.0,
      "totalCostUsd": 4.12
    }
  ],
  "monthlyUsage": [
    {
      "month": "2024-01",
      "inputTokens": 120000,
      "outputTokens": 28000,
      "cacheReadTokens": 410000,
      "cacheCreationTokens": 18000,
      "totalTokens": 576000,
      "totalCostUsd": 12.4,
      "requestCount": 420,
      "activeDays": 11
    }
  ]
}

recommendations is always an empty array — the earlier cache-blind model-downgrade heuristic was removed. The field is retained so the serialized array keeps a stable element type for existing clients.

Sub-session boundary review

Sub-sessions are detected automatically; these two endpoints let a human correct a boundary and measure how often that happens. (To rename a sub-session in v3, use PATCH /v1/score_v3/sub-sessions/:id instead — that is a different operation.)

POST /v1/sub-sessions/:id/override

Submit a human override on an automatically-detected sub-session. Ownership is enforced — an override on a sub-session outside the caller’s org/developer scope returns 400.

POST /v1/sub-sessions/<id>/override
Authorization: Bearer gck_your_key
Content-Type: application/json

{
  "field": "label",
  "action": "rename",
  "payload": { "new_label": "Fix auth flow timeout" }
}

Body field	Type	Description
`field`	string	One of `boundary`, `completion`, `rollback`, `label`
`action`	string	Action string; must be legal for the chosen `field`
`payload`	object	Optional. `rename` expects `{"new_label": "…"}`; `split_at_turn` expects `{"split_turn_idx": N}`

Response (camelCase):

{
  "subSessionId": "…",
  "field": "label",
  "action": "rename"
}

GET /v1/sub-sessions/accuracy

Agreement metrics for sub-session boundary detection — how often the automatic boundaries stand without a human override, per field.

GET /v1/sub-sessions/accuracy?window_days=28
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
`window_days`	integer	28	Lookback window (clamped to 1–90)

Response (camelCase):

{
  "rows": [
    {
      "field": "boundary",
      "overrides": 3,
      "subSessions": 120,
      "agreementRate": 0.975
    }
  ],
  "windowDays": 28
}

agreementRate is 1 − overrides / subSessions, and is null when there were no sub-sessions in the window.