Skip to main content

​
Scores API

Retrieve risk scores for events, view aggregated analytics, and inspect full score decompositions.

​
Endpoints

GET /scores/{customer_id}

Paginated list of scores with filtering by risk level and date range

GET /scores/{customer_id}/summary

Aggregated risk statistics across all scored events

GET /scores/event/{event_id}

Full score detail with decomposition for a specific event

​
Score Response Fields

Every score includes these core fields:
FieldTypeDescription
event_idstringEvent that was scored
final_scoreintRisk score 0-100
risk_levelstringnone / low / medium / high / critical
reasoningstringHuman-readable scoring explanation
violationsstring[]Policy violations detected
scoring_sourcestringgraph_reasoner or graph_reasoner+llm
compliance_refsstring[]Compliance article references
mitigationsstring[]Recommended remediation steps
graph_scoreintGraphReasoner’s score
llm_scoreintLLM’s score (if invoked)
llm_fallbackboolWhether LLM was invoked
confidencefloatScoring confidence 0.0-1.0
gnn_scorefloatGNN structural score
cache_hitboolWhether a cached score was used
scored_atdatetimeWhen the event was scored

​
Score Decomposition

The score_decomposition field provides full 4-layer breakdown: 
{
  "score_decomposition": {
    "intrinsic_action_risk": {
      "score": 25,
      "weight": 0.15,
      "components": {
        "verb_base": 10,
        "data_sensitivity": 2.5,
        "target_scope": 1.0,
        "mcp_trust": 1.0
      }
    },
    "structural_gnn": {
      "score": 68,
      "weight": 0.45,
      "confidence": 0.82
    },
    "policy_violation": {
      "score": 85,
      "weight": 0.40,
      "matched_policies": ["block_pii_sensitive"]
    },
    "temporal_modifier": {
      "multiplier": 1.4,
      "components": {
        "rate_anomaly": 1.4,
        "sequence_novelty": 1.0,
        "time_anomaly": 1.0,
        "session_drift": 1.0
      }
    }
  }
}

​
Summary Statistics

The summary endpoint provides aggregated risk distribution: 
{
  "customer_id": "eec10443-1791-4584-86d6-478af5babebd",
  "total_events": 48293,
  "avg_score": 12,
  "none_count": 41200,
  "low_count": 5100,
  "medium_count": 1500,
  "high_count": 450,
  "critical_count": 43
}

​
Filtering

Use query parameters to filter the scores list: 
# Only critical events in the last 24 hours
curl "https://api-production-56df.up.railway.app/scores/eec10443-1791-4584-86d6-478af5babebd\
?risk_level=critical\
&from_date=2026-02-25T00:00:00Z\
&page=1\
&per_page=20" \
  -H "X-API-Key: sk-acme-b96cb84498324444"