Intelligence 엔드포인트

Intelligence 엔드포인트(endpoint)는 Prism API의 운영 신호를 노출합니다: throttle 영향, 모델 rightsizing 추천, 서브세션(sub-session) 경계 검토. 모든 엔드포인트는 인증된 조직과 개발자(developer) 범위(scope)로 제한됩니다.

Throttle

GET /v1/intelligence/throttle

인증된 개발자에 대한 속도 제한 이벤트, 지연 스파이크, 서비스 장애 감지와 함께 추정 손실 시간 요약 및 완화 추천을 제공합니다.

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

파라미터	타입	기본값	설명
`from`	ISO8601	—	시작 시간
`to`	ISO8601	—	종료 시간
`tz_offset`	integer	`0`	UTC 기준 동쪽으로의 분 단위 타임존 오프셋

응답 (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은 항상 false입니다 — 좁은 개인 기간에서의 예산 축소는 실제 실패로 취급되어, 축소 보고 대신 오류를 발생시킵니다. confidence, incidentName, incidentUrl은 service_outage 이벤트에만 나타납니다.

GET /v1/intelligence/throttle/team

throttle 리포트의 팀 범위 변형입니다. team_id가 필요하며, 호출자의 팀 멤버십은 서버 측에서 검증되고 클라이언트가 보낸 team_id는 그 검사 이상으로는 신뢰되지 않습니다.

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

파라미터	타입	기본값	설명
`team_id`	UUID	— (필수)	집계할 팀
`from`	ISO8601	—	시작 시간
`to`	ISO8601	—	종료 시간
`tz_offset`	integer	`0`	UTC 기준 동쪽으로의 분 단위 타임존 오프셋

개인 엔드포인트와 동일한 ThrottleImpactResponse 형태를 반환합니다. 개인 엔드포인트와 달리, 제한된 파일/바이트 읽기 예산이 텔레메트리를 누락시키면 팀 읽기는 isPartial: true로 설정할 수 있습니다 — 이때 카운트는 요청한 범위보다 적게 포괄합니다.

Rightsizing

GET /v1/intelligence/rightsizing

저장된 사용량에서 직접 계산한 모델 및 tier 사용 요약(백그라운드 워커 없음).

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

파라미터	타입	기본값	설명
`from`	ISO8601	90일 전	시작 시간
`to`	ISO8601	현재	종료 시간

응답 (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는 항상 빈 배열입니다 — 이전의 캐시를 고려하지 않던 모델 하향 휴리스틱이 제거되었습니다. 이 필드는 직렬화된 배열이 기존 클라이언트를 위해 안정적인 요소 타입을 유지하도록 남겨두었습니다.

서브세션 경계 검토

서브세션은 자동으로 감지됩니다. 이 두 엔드포인트는 사람이 경계를 보정하고 그런 일이 얼마나 자주 일어나는지를 측정할 수 있게 합니다. (v3에서 서브세션 이름을 변경하려면 대신 PATCH /v1/score_v3/sub-sessions/:id를 사용하세요 — 그것은 다른 작업입니다.)

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

자동 감지된 서브세션에 사람 오버라이드를 제출합니다. 소유권이 강제됩니다 — 호출자의 조직/개발자 범위 밖 서브세션에 대한 오버라이드는 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" }
}

바디 필드	타입	설명
`field`	string	`boundary`, `completion`, `rollback`, `label` 중 하나
`action`	string	액션 문자열; 선택한 `field`에 대해 유효해야 함
`payload`	object	선택 사항. `rename`은 `{"new_label": "…"}`을, `split_at_turn`은 `{"split_turn_idx": N}`을 기대함

응답 (camelCase):

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

GET /v1/sub-sessions/accuracy

서브세션 경계 감지에 대한 합의 메트릭 — 필드별로, 자동 경계가 사람 오버라이드 없이 유지되는 빈도.

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

파라미터	타입	기본값	설명
`window_days`	integer	28	조회 기간 (1–90으로 제한)

응답 (camelCase):

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

agreementRate는 1 − overrides / subSessions이며, 기간 안에 서브세션이 없었으면 null입니다.