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
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.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).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.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.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
days_back, window_hours (dream-grouped tenants only), open_problems, reopened, total_problems, signals_attributed, explained_coverage_pct.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).
unexplained_signals.unexplained_signals_scope says which quantity unexplained_signals holds: current_plus_historical here and in the problem detail remainder.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.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.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.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.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.How many provisional problems there are in all; more than the length of
emerging when limit cut it.When things were last computed:
book_computed_at, latest_assignment_at, lag_seconds, verification (counts by status).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
list_version of the first page; a later page is cut from the same read while it is cached (5 minutes).severity (the dream’s rank), users, or silent (share of users who never noticed): the dashboard table’s columns.Response fields
The dream run the list comes from:
run_id, window_end, window_hours, incidents, unsorted, users, users_grouped.problems (every problem the table shows), incidents, unsorted_incidents, users, users_grouped, pinned_problem_ids, and previous (the window before, with comparable).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.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.
1–50 incidents per page.
incidents_total counts them all; next_offset starts the next page.GET /problems/:id
Full detail for one problem. Returns200 with found: false for an unknown or malformed ID — not 404.
Response fields
The surviving problem ID, the ID you requested, and whether a merged-away ID was folded to its survivor.
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.Rank history:
{run_ts, rank_score, total_attributions, rubric_version, coverage_overall} per computation run, newest first.Child problems for macro problems:
{problem_id, display_name, cause_statement, lifecycle, version}.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.A first page of evidence rows (see
/problems/:id/evidence for the full paginated set and field list).First page of investigation reports:
{items[], has_more, next_cursor} (full set on /problems/:id/reports).Lineage events:
{problem_id, event_id, event_kind, related_problem_id, rubric_version, causal_content_version, reason, created_ts}.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.Precomputed narrative blocks (
executive_summary, causal_chain, suggested_investigation, representative_story_keys, limitations) plus computation metadata. null until a dossier has been generated.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
Each report hasreport_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
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 theevidence 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
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
Required for
flag_attribution. A non-UUID value returns 400; a UUID that does not belong to this problem returns 404.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.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 (whichmoda problems feedback sends): it flags issues with what the Data API returned, and it is what moda feedback sends. Returns 202.
Body fields
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.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 asaffected.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 anodeIdcan 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 someinUseCaseConversationscan’t count asaffectedin any window, split by reason.stalemeans the trace was re-segmented after the run, so the run’s use-case membership points at a superseded segment.ineligiblemeans the segment’s current version was built by a different segment embedding version or source.missingmeans the segment no longer exists. These count again once a classification run includes the trace’s current segments.
occurred_at and trend buckets use the same value.