Skip to main content
These endpoints read the per-trace signals Moda detects on ingested data: user frustration and other emotions, tool failures, and grounding (hallucination) results. Detections typically appear within minutes of ingest. The same data drives the Signals dashboard.

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

integer
default:"7"
1–90.
integer
default:"10"
1–20. This endpoint’s cap is 20, lower than the general 100.
integer
default:"0"
0–10,000.
string
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.
string
Scope every figure in the response to one trace. An empty value returns 400.

Response fields

object
total_analyzed (traces analyzed in the window), frustrated_count, at_risk_count (risk score at least 0.5 but not frustrated), frustration_rate_pct.
object
Map of frustration signal to count, across frustrated traces only.
array
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.
object
limit, offset, total, has_more.
object
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

integer
default:"7"
1–90.
integer
default:"10"
1–20.
integer
default:"0"
0–10,000.
string
Filter the paginated detections list (and its total) to one family. The summary and signal_breakdown always cover all families. Unknown values return 400.
string
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.
string
Scope every figure in the response to one trace. An empty value returns 400.
string
default:"1"
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.
string
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

object
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).
array
{family, signal, count} rows across detected traces.
array
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).
object
limit, offset, total, has_more, detected, at_risk. total counts detected plus at-risk rows (is_detected: false); use detected for the detection count.
object
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

integer
default:"7"
1–90.
string
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

object
total (failed calls), total_calls (all calls), conversations (traces with a failure), tools (with a failure), failure_rate_pct.
array
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

string
Filter examples (and the pagination total) to one error subtype. The subtypes breakdown is always unfiltered.
integer
default:"7"
1–90.
integer
default:"5"
1–20.
integer
default:"0"
0–10,000.
string
default:"1"
0 or false skips each example’s embedded trace window: conversation is null.

Response fields

string
array
{subtype, count, conversation_count, sample_error, last_seen} per error subtype.
array
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.
object
limit, offset, total, has_more.

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

integer
default:"7"
1–90.
string
default:"calls"
calls, failure_rate, failures (failed calls), traces, or last_seen. All descending; tool_name breaks ties.
Only tools whose name contains this text (case-insensitive).
string
Only tools with this effect direction: read, write, send, spawn, compute, or unknown.
integer
default:"50"
1–200.
integer
default:"0"
0–10,000.

Response fields

object
total_calls, unique_tools, and total_conversations (traces with a call) for the window and filters.
array
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.
object
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. Returns 404 when the tool has no calls in the window.

Query parameters

integer
default:"7"
1–90. Under 7 days, usage is hourly; otherwise daily.

Response fields

object
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.
object
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.
array
{timestamp, calls, failed_calls} per bucket (see window.bucket).
object
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).
array
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.
array
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

integer
default:"7"
1–90.
integer
default:"10"
1–20.
integer
default:"0"
0–10,000.
string
Scope the response — including the summary aggregates — to one trace.
string
contradicted or verified. Filters the detections list and its total.
string
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

object
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).
array
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.
object
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.