Skip to main content
Problems are recurring root causes that Moda discovers by grouping signals (frustrations, tool failures, and other detections) across traces. Signal attributions land within minutes, and the ranked list is updated automatically as evidence accumulates. These endpoints mirror the Problems dashboard and add a feedback channel that steers discovery. Problem IDs are UUIDs. If a problem was merged into another, its old ID still resolves — responses report the surviving ID in problem_id and set alias_resolved: true.

GET /problems

The ranked problem list (the Book) with coverage and freshness metadata. It is read by the same loader as the dashboard’s Problems list, so counts, ranking, trust and the date range are the dashboard’s. For a tenant with a dream grouping published, the dashboard shows that grouping by default: read it with GET /problems/dream.

Query parameters

integer
default:"30"
1–90. The range the counts cover. For a tenant whose Problems are dream-grouped (message-windowed), the counts are recounted live for the range and summary.window_hours reports the rollup’s own window.
integer
default:"25"
1–200 rows per page, applied to problems and untrusted separately. Also caps emerging and hierarchy.macros. The first page of the rank order may carry up to two extra rows: the open problems with the most affected users, when the rank cut dropped them (they appear again at their own rank on a later page; dedupe by problem_id).
integer
default:"0"
Row to start each partition at: next_offset of the previous page.
string
list_version of the first page, passed with every later offset, so the page is cut from the same read. A later page whose list_version differs came from a newer list: restart from offset=0.
string
default:"rank"
rank (the Book’s order), users, signals, problems or signal:<family>: the dashboard table’s orders, applied to each partition before the page is cut.
string
default:"desc"
desc or asc, for a sort other than rank.
string
builtin:<key> or a saved cohort id: only the problems the cohort’s users hit, each with cohort: {attributions, conversations}. The cohort’s membership snapshot is refreshed first, as the dashboard does.

Response fields

object
days_back, window_hours (dream-grouped tenants only), open_problems, reopened, total_problems, signals_attributed, explained_coverage_pct.
object
The tenant-wide coverage meter: attributed_signals, unexplained_signals, unexplained_signals_scope, unexplained_signals_current, unexplained_signals_historical_only, coverage_pct, historically_attributed_signals, historical_coverage_pct.Here unexplained_signals is everything the live problem list doesn’t explain, and it splits into two parts:
  • unexplained_signals_current: signals in the window with no attribution at all.
  • unexplained_signals_historical_only: signals attributed only to problems that are no longer live (retired, resolved, or not in the latest ranking run).
The two parts always add up to unexplained_signals.unexplained_signals_scope says which quantity unexplained_signals holds: current_plus_historical here and in the problem detail remainder.
array
The trusted ranked list — only rows whose verification_status is current, ordered by rank. Each row has problem_id, display_name, cause_statement, lifecycle (open, fixed_monitoring, reopened, resolved), rank_score, rubric_version, total_attributions, family_weighted_count, affected_users, affected_conversations (traces affected), abandonment_rate, recency_score, trend_score, multi_family, family_counts, coverage_overall, coverage_by_family, audit_pass_rate (or null), verification_status, verified_causal_version. When the Book keeps a curated shortlist, pressing_rank is the row’s place on it (null when it is not on it); rank_basis is v4_impact when rank_score is the problems v4 impact score; incidents counts a dream-grouped tenant’s incidents in the range. An empty name falls back to the cause, as the dashboard titles it.
array
Same row shape as problems, for rows whose verification is failed, unverified, or stale. They are still live problems and still visible, but never ranked. Treat failed and unverified rows as hypotheses; stale rows rank again after re-verification.
integer | null
Where the next page of problems and untrusted starts, or null on the last page. offset, list_version, sort (and dir, cohort when set) echo the page.
object
macros[] — macro themes grouping leaf problems (problem_id, display_name, display_description, tier, child_count, children[]), at most limit of them — macro_total (all live macros), and unparented_leaf_count.
array
Provisional problems not yet in the ranked list, at most limit of them, most supported first: problem_id, display_name, display_description, family (or null), evidence_support (report_backed_members, attribution_count), verification_status, provisional: true.
integer
How many provisional problems there are in all; more than the length of emerging when limit cut it.
object
When things were last computed: book_computed_at, latest_assignment_at, lag_seconds, verification (counts by status).
integer
Feedback rows submitted but not yet applied.
string[]
Human-readable notes, empty when there are none. When problems is empty but untrusted or emerging has items, a warning says how many sit in each (with the untrusted verification breakdown). An empty problems list does not mean the tenant has no problems.

Example

This example is trimmed for readability: with limit=1 only the top-ranked row is shown, and the untrusted rows implied by the verification counts (stale: 1, unverified: 1) are omitted, as are offset, next_offset and list_version.

GET /problems/dream

The dream-grouped Problems list: what the dashboard’s Problems page shows by default when the tenant has a dream grouping published. Read by the dashboard’s own loader. A tenant without one gets {"available": false, "view": "dream"}, and its Problems are GET /problems, as on the dashboard.

Query parameters

integer
1–90 days ending now. Absent: the dream run’s whole window, the dashboard’s default.
integer
default:"25"
1–200 problems per page.
integer
default:"0"
next_offset of the previous page. Pass list_version with it.
string
list_version of the first page; a later page is cut from the same read while it is cached (5 minutes).
string
default:"severity"
severity (the dream’s rank), users, or silent (share of users who never noticed): the dashboard table’s columns.
string
default:"desc"
desc or asc.
string
builtin:<key> or a saved cohort id: every count comes from the cohort’s users.

Response fields

boolean
true when the tenant has a dream grouping published (the dashboard then shows it).
object
The dream run the list comes from: run_id, window_end, window_hours, incidents, unsorted, users, users_grouped.
object
problems (every problem the table shows), incidents, unsorted_incidents, users, users_grouped, pinned_problem_ids, and previous (the window before, with comparable).
array
One page, in the table’s order. Each row has problem_id (a Book problem id: GET /problems/:id reads its dossier), name, category, cause_statement, fix, owner, component, lifecycle, pinned, incidents, users, silent_users, silent_share_pct, noticed_counts, trend, previous_incidents (when comparable), severity (tier P0–P3, rank, alert, worst), dream_rank and first_incident_at.
array
First page only: the most severe rated incidents of the shown problems.
integer | null
Where the next page starts, or null. sort, dir, offset, limit and list_version echo the page.

GET /problems/dream/:id

One dream problem as the dashboard’s dream page shows it: its definition, scores, counts and severity, with a page of its incidents (the validator’s verdict, quoted messages, assumptions and severity rating), most serious first. 404 when the problem is not in the dream grouping; {"available": false} when the tenant has none.
integer
default:"5"
1–50 incidents per page. incidents_total counts them all; next_offset starts the next page.
integer
default:"0"
First incident to return.
integer
1–90. Absent: the dream run’s whole window.

GET /problems/:id

Full detail for one problem. Returns 200 with found: false for an unknown or malformed ID — not 404.

Response fields

boolean
false when the ID does not resolve to a problem; all other blocks are then empty or null.
string / string / boolean
The surviving problem ID, the ID you requested, and whether a merged-away ID was folded to its survivor.
object | null
The same row shape as the list on GET /problems.
object | null
The latest problem definition: version, cause_statement, display_name, display_description, lifecycle, parent_problem_id, change_reason, match_criteria, counter_examples, scope_hints, updated_at, tier (macro or leaf), provisional, affected_surface, causal_content_version.
array
Rank history: {run_ts, rank_score, total_attributions, rubric_version, coverage_overall} per computation run, newest first.
array
Child problems for macro problems: {problem_id, display_name, cause_statement, lifecycle, version}.
object
audit_pass_rate, judge_audit ({passed, total}), counterfactual_replay ({passed, total}), and samples[] — individual verification checks with kind, passed, rubric_version, conversation_id, segment_id, rationale, verified_at.
array
A first page of evidence rows (see /problems/:id/evidence for the full paginated set and field list).
array
Per-trace {conversation_id, user_id, signal_count, family_counts, last_signal_at} rollups.
object
The same tenant-wide coverage meter as the list endpoint.
object
First page of investigation reports: {items[], has_more, next_cursor} (full set on /problems/:id/reports).
array
Lineage events: {problem_id, event_id, event_kind, related_problem_id, rubric_version, causal_content_version, reason, created_ts}.
object
known_users, unknown_identity_conversations, total_conversations, identity_coverage_pct — impact is split so traces without a known user are never reported as zero users.
object
tier, parent (or null), children[].
object | null
Precomputed narrative blocks (executive_summary, causal_chain, suggested_investigation, representative_story_keys, limitations) plus computation metadata. null until a dossier has been generated.
array
Representative examples, each {story_kind, evidence} where story_kind is one of top_confidence, replay_verified, newest.

Example

The example trims header to a few fields for readability; the live response returns the complete list-row shape documented under GET /problems.

GET /problems/:id/reports

Investigation reports for one problem, keyset-paginated.

Query parameters

integer
default:"20"
1–50.
string
The next_cursor from a previous page.
Each report has report_id, conversation_id, segment_id, status (investigated, no_problem, or rejected), problem_found, mechanism, narrative, citations[] ({path, ref, quote}), signals_explained, signals_total, signals_explained_ids[], signals_unexplained_ids[], suspected_surface, severity, confidence, primary_family, investigated_at.

GET /problems/:id/conversations

Traces attributed to one problem, keyset-paginated, with per-trace counts and an anchor for deep-linking.

Query parameters

integer
default:"25"
1–50.
string
The next_cursor from a previous page.
string
Filter to one signal family (for example tool_failure, emotion).
string
How the trace joined the problem: rubric_match or local_causal_chain.
Use latest_anchor.anchor_msg_index with /conversations/:id/context to read the moment the signal fired.

GET /problems/:id/evidence

All evidence attributions for one problem, keyset-paginated. Rows have the same shape as the evidence block on GET /problems/:id: attribution_id, conversation_id, segment_id, anchor_signal_id, anchor_msg_index, signal_family, signal_type, confidence, causal_rationale, door, replay_verified (or null), evidence_snippet, dedup_count, user_id, assigned_at, snippet_parsed (structured parse of evidence_snippet, null for legacy raw-text rows), snippet_legacy_raw_text, report_id (or null for fast-lane rows).

Query parameters

integer
default:"25"
1–50.
string
The next_cursor from a previous page.

POST /problems/:id/feedback

Records feedback on a problem. Feedback does not edit the problem directly — it is incorporated automatically. mark_fixed also arms automatic reopening if the problem recurs. This is the endpoint behind moda problems feedback.

Body fields

string
required
One of mark_fixed, dismiss, flag_attribution, rename.
string
Up to 2,000 characters. Required for dismiss and flag_attribution.
string
Required for flag_attribution. A non-UUID value returns 400; a UUID that does not belong to this problem returns 404.
string
Up to 255 characters. Required for rename.
string
default:"data-api"
Recorded as the acting identity, up to 255 characters.
This endpoint is idempotent: feedback_id is derived deterministically from the payload, so resubmitting identical feedback while it is still pending returns the same feedback_id with duplicate: true and records nothing new. Safe to retry.
A malformed (non-UUID) problem ID returns 400.

GET /problems/:id/history

One problem’s incidents and users per UTC day, from the dashboard’s problem history loader, and the window against the window of equal length before it. A merged problem’s history is its survivor’s. moda problems get <id> --trend reads this endpoint.

GET /problems/:id/feedback

Feedback history for one problem, with pending/consumed state.

POST /feedback

General feedback about data quality — a wrong cluster label, a mismatched frustration cause, missing data. This is separate from problem feedback (which moda problems feedback sends): it flags issues with what the Data API returned, and it is what moda feedback sends. Returns 202.

Body fields

string
required
One of bad_cluster_label, mismatched_frustration, missing_data, noisy_data, wrong_tool_failure, incorrect_loop, api_quirk, false_positive_attribution, misrouted_fix, harness_bug, other. Any other value is stored as other, with the submitted value in refs.raw_category.
string
default:"low"
One of info, low, medium, high.
string
Up to 4,000 characters describing what looked wrong.
string
One of cli, sdk, ui.
string
The agent submitting the feedback, up to 64 characters.
string
Up to 32 characters.
object
Free-form references, for example {"conversation_id": "...", "tool_name": "..."}.
object
Free-form context about the command or query that produced the suspect result.
Unlike problem feedback, this endpoint is not idempotent — every request creates a new feedback record with a random feedback_id. Do not retry it automatically.

Next steps

  • Dashboard: Problems — the same problem book as a kanban with dossiers.
  • Signals — the raw detections that problems are built from.
  • Traces — read the context around any evidence anchor.

Problem impact within use cases

GET /api/v1/data/problem-impact connects attributed problem evidence to the use-case segments in which it occurred. Authenticate with the same API key as other Data API endpoints; tenant scope comes from that key. Select a node, a problem, or both. catalog lists available use cases and problems. overview returns the distinct affected share for root use cases (or the selected node’s children). A parent problem includes its current leaf problems. affected-use-cases returns affected counts without full population denominators. trace-use-cases resolves current use-case membership from a problem’s attributed segments for the specified traces across their history; it does not apply the days window. The response includes runId, resolved problemId, window, nodes, problems, rows, evidence, nextCursor, and computedAt. Metric rows have node_id, problem_id, and period (current or previous). An empty problem_id identifies the full analyzed population; * identifies the distinct union of affected traces across selected problems. Use the empty-ID row’s analyzed denominator for each problem’s percentage. A problem-only metrics response includes only affected use cases, with each denominator covering that use case’s full analyzed population. Never add problem counts to produce a distinct total. Trend rows include a UTC bucket date and span the current and preceding windows, or all available history for days=all without a preceding comparison window. A trend row’s period is previous when its bucket date is before the first day of the window (window.from) and current otherwise, so each date is one row. Missing dates have no analyzed population and no rate. affected / analyzed is affected share, not task failure rate. traces counts distinct conversations with matching current segments. analyzed counts conversations containing at least one matching analyzed segment, including negative analysis outcomes. segments and analyzed_segments expose partial analysis coverage. users counts distinct nonempty identities on affected evidence; identified_traces provides identity coverage. Evidence returns up to 25 distinct conversations per page with the exact segment_id and zero-based anchor_msg_index. Continue using nextCursor, runId, window.to, and the original filters. A cursor from another scope is rejected. Unmapped evidence is excluded from scoped results. These are live reads of the current classification and attribution records, using segment occurrence timestamps. They are not stored historical snapshots: regeneration, merges, transfers, and retractions can change past results. Individual source reads can observe concurrent pipeline updates. 409 requests a classification refresh; query failures remain errors, never zero-count results. No materialized impact counters or refresh jobs are added. Like the dossier, every impact count excludes retracted reports and detections a review marked as false positives. Impact counts only attributions whose segment belongs to a use case in the current classification run and occurred inside the window, so a problem’s affected count can be lower than the dossier’s affected conversations, or zero. For metrics, trend, evidence, and affected-use-cases requests with a problemId, the response also includes attributionCoverage, which counts over all time, and a warnings list that explains the gap:
  • attributedConversations: the conversations attributed to the problem. This is the same population as the dossier’s affected conversations: retracted reports and detections a review marked as false positives are excluded.
  • inUseCaseConversations: the attributed conversations with at least one attributed segment in a use case in scope. Only these can count as affected.
  • outsideUseCaseConversations: the attributed conversations that impact can’t place in the selected scope. They split into the three counts below.
  • otherUseCaseConversations: conversations the run classified into a different use case. Only a request with a nodeId can have these.
  • readerOnlyConversations: conversations whose only evidence is conversation-level (reader) evidence, which has no thread segment.
  • unclassifiedConversations: conversations with attributed segments that the run didn’t place in any use case, for example traces ingested after the run.
  • uncountableInUseCase: present only when some inUseCaseConversations can’t count as affected in any window, split by reason. stale means the trace was re-segmented after the run, so the run’s use-case membership points at a superseded segment. ineligible means the segment’s current version was built by a different segment embedding version or source. missing means the segment no longer exists. These count again once a classification run includes the trace’s current segments.
The window uses the segment’s effective occurrence time. That is the message time, or the conversation’s first ingest time for replayed history whose message times are placeholders from before 2022. Window filters and displayed times such as occurred_at and trend buckets use the same value.