GET /frustrations
Frustration detections with evidence, verbatim user quotes, and an embedded context window. Reads the same emotion-engine data as/emotions with family=frustration (windowed by analysis time), so counts match /emotions and the Signals dashboard.
Query parameters
Scope every figure in the response (summary, signal breakdown, list, and total) to one end user. A detection belongs to the first non-empty
user_id seen in its trace. An empty value returns 400.Response fields
total_analyzed (traces analyzed in the window), frustrated_count, at_risk_count (risk score at least 0.5 but not frustrated), frustration_rate_pct.Frustrated and at-risk traces, ordered by
frustration_score then risk_score. Each row has conversation_id (the trace ID), is_frustrated, frustration_score, risk_score, trajectory, target, primary_cause, evidence, user_quotes[] (turn, quote, signal), expressed_signals[], observed_signals[], key_turns[], message_count, detected_at, and conversation — an embedded context window from the trace (same shape as /conversations/:id/context) centered on the first key turn, or null.enabled (true, false, or null), setting ("signals.frustration"), and optional reason (for example "dogfood_tenant"). This is the tenant processing switch that gates emotion and frustration analysis. When enabled is false, no new traces are analyzed, so zero counts mean “not analyzed”, not “no frustration”. null means the setting couldn’t be read, so treat zeros as unconfirmed. Missing settings default to enabled.Example
GET /emotions
Multi-family emotion detections. Moda scores seven families,frustration, sadness, confusion, anxiety, trust, disapproval (shown in the dashboard as Redirection) and positive, with one detection row per trace and family. The first five are negative; disapproval and positive never count toward negative_rate_pct. See Signals in the dashboard for the full 17-signal taxonomy.
Query parameters
Filter the paginated
detections list (and its total) to one family. The summary and signal_breakdown always cover all families. Unknown values return 400.Scope every figure in the response (summary, signal breakdown, list, and total) to one end user. A detection belongs to the first non-empty
user_id seen in its trace. An empty value returns 400.0 or false skips the embedded trace windows: every detection’s conversation_context is null and the response is much smaller. Use it when paging the list and opening traces separately with GET /conversations/:id/context.builtin:<key> or a saved cohort id; needs group_by=trace. The dashboard Signals list’s cohort scope: only traces of the cohort’s members, in the summary and the list. The cohort’s membership snapshot is refreshed first when it is missing or stale, as the dashboard does; an unknown saved cohort id returns 404, and the response echoes cohort.Response fields
conversations_analyzed (traces analyzed), by_family (detected count per family), negative_rate_pct (share of analyzed traces with any negative-family detection), positive_rate_pct, and repair_rate_pct (share of negative detections whose trajectory resolved).Detected and at-risk rows, ordered by score. Each has
detection_id, conversation_id, user_id, family, is_detected, score, risk_score, trajectory, elicitor, primary_cause, evidence, user_quotes[], expressed_signals[], observed_signals[], key_turns[], downgrade_reason, detection_grade (rlm for deep analyses, light for the positive-family fast path), message_count, detected_at, and conversation_context (embedded context window or null).limit, offset, total, has_more, detected, at_risk. total counts detected plus at-risk rows (is_detected: false); use detected for the detection count.enabled (true, false, or null), setting ("signals.frustration"), and optional reason (for example "dogfood_tenant"). This is the tenant processing switch that gates emotion and frustration analysis. When enabled is false, no new traces are analyzed, so zero counts mean “not analyzed”, not “no frustration”. null means the setting couldn’t be read, so treat zeros as unconfirmed. Missing settings default to enabled.Example
GET /tool-failures
Per-tool failure KPIs for the window. Only tools with at least one failure are listed. This endpoint has no pagination; use/tool-failures/:toolName for examples.
Query parameters
builtin:<key> or a saved cohort id: the dashboard Tool Failures leaderboard for the cohort’s traces, read through the page’s own loader (source: "dashboard_tool_failures"). It counts failures only: summary is total, conversations, tools, and each tool carries top_category and failure_family instead of call totals and failure rates. The cohort’s membership snapshot is refreshed first when it is missing or stale, as the dashboard does; an unknown saved cohort id returns 404, and the response echoes cohort.Response fields
total (failed calls), total_calls (all calls), conversations (traces with a failure), tools (with a failure), failure_rate_pct.Ordered by
failure_count descending. Each has tool_name, failure_count, total_count, failure_rate_pct, conversation_count (traces affected), top_error (a sample error message, truncated to 80 characters), last_seen.Example
GET /tool-failures/:toolName
Failure detail for one tool: a breakdown by error subtype plus individual examples with embedded trace context. Subtype names come from your tenant’s failure taxonomy — they are labels, not a fixed enum.Query parameters
Filter
examples (and the pagination total) to one error subtype. The subtypes breakdown is always unfiltered.Response fields
Newest first. Each has
failure_id, conversation_id, error_message, error_subtype, tool_input (truncated), msg_index, detected_at, and conversation — an embedded context window from the trace centered on the failing call, or null.Example
GET /tools
The tool catalog: every tool called in the window, failing or not, with the figures of the dashboard Tool catalog (same query).calls, failed_calls, and success_rate_pct count recorded tool receipts. /tool-failures counts classified tool failures instead, so the two can differ; metric_note says so in every response.
Query parameters
calls, failure_rate, failures (failed calls), traces, or last_seen. All descending; tool_name breaks ties.Response fields
total_calls, unique_tools, and total_conversations (traces with a call) for the window and filters.Each has
tool_name, calls, failed_calls, success_rate_pct, failure_rate_pct, conversation_count, effect_direction (the most common), target_system (the most common), and last_seen.limit, offset, total (tools matching), returned, has_more, and next_offset when has_more is true.Example
GET /tools/:name
One tool from the catalog: call stats, its registered definition and observed payload fields, usage over time, effect profile, top failure categories with the newest failure of each, and recent calls. Returns404 when the tool has no calls in the window.
Query parameters
Response fields
calls, failed_calls, success_rate_pct, failure_detections (classified failures, as in /tool-failures/:toolName), conversation_count, user_count, first_seen, last_seen, primary_class_id, primary_class_description.registered: the tool definition registered for this name (description, schema, source, is_active, updated_at), or null. observed_fields: keys seen in recorded call inputs, each with inferred_type, call_count, call_pct, and up to 10 common_values. Also payloads_sampled and invalid_payloads.total_failures, categories_total, and the top 10 categories, each with category (the subtype value of /tool-failures/:toolName), label, failure_family, likely_cause, action_hint, count, conversation_count, sample_error, last_seen, and latest_failure (conversation_id, msg_index, tool_use_id, detected_at).Up to 10 recorded classes of use, each with
tool_class_id, description, effect_direction, target_system, target_resource, calls, sample_input, and example_inputs.The 10 newest calls:
conversation_id, msg_index, success, inputs, conversation_timestamp, and the call’s class and target.Example
GET /hallucinations
Hallucinations: agent messages that told the user something the trace shows is false. Each comes from a Problems incident the validator kept as a false statement (incident_id); rows from before that change are the earlier grounding checks of agent claims against the trace’s world state and tool results, kept as history.
The per-message
detections list contains only two kinds of rows: contradicted (a claim contradicted by evidence) and verified (a claim confirmed by evidence). Ungrounded claims — statements with no supporting or contradicting evidence — appear only in the summary aggregates and are never listed per message.Query parameters
builtin:<key> or a saved cohort id; needs group_by=trace. Only traces of the cohort’s members, in the summary and the list. The cohort’s membership snapshot is refreshed first when it is missing or stale, as the dashboard does; an unknown saved cohort id returns 404, and the response echoes cohort.Response fields
Counts across all scored claims:
total_scored, contradicted_count, verified_count, ungrounded_count, ungrounded_rate (0–1), conversations_scored (traces scored), conversations_with_contradiction, and rule_breakdown[] ({source, rule_id, count} for contradictions).Contradicted rows first, then by confidence. Each has
conversation_id, message_index, unit_id, segment_id, kind (contradicted or verified), label, confidence, source, rule_id, model_id, violated_receipt_id (or null), violated_slot_key, violated_thread_id, offending_substring, evidence_quote, cws_high_water_msg_index, message_count, incident_id, detected_at. incident_id names the Problems incident the hallucination comes from; it is null for rows from before hallucinations came from validated incidents.limit, offset, total. This endpoint does not return has_more; page until fewer than limit rows come back or offset + limit >= total.Example
Next steps
- Traces — pull a wider context window around any detection’s key turn.
- Problems — signals grouped into ranked root-cause problems.
- Dashboard: Signals — the same detections with the full emotion and failure taxonomies.