Problems - Moda

Problems are recurring root causes that Moda discovers by grouping signals (frustrations, tool failures, and other detections) across conversations. 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 with coverage and freshness metadata.

Query parameters

integer

default:"30"

1–90. Bounds which computation runs count toward the list.

integer

default:"25"

1–25. This endpoint’s cap is 25.

Response fields

object

days_back, open_problems, reopened, total_problems, signals_attributed, explained_coverage_pct.

object

The tenant-wide coverage meter: attributed_signals, unexplained_signals, coverage_pct, historically_attributed_signals, historical_coverage_pct.

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, agg_prm_delta, 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.

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.

object

macros[] — macro themes grouping leaf problems (problem_id, display_name, display_description, tier, child_count, children[]) — and unparented_leaf_count.

array

Provisional problems not yet in the ranked list: problem_id, display_name, display_description, family (or null), evidence_support (report_backed_members, attribution_count), verification_status, provisional: true.

object

When things were last computed: book_computed_at, latest_assignment_at, lag_seconds, discovery (latest session stats or null), verification (counts by status), remainder_backlog (pending_groups, pending_mass).

integer

Feedback rows submitted but not yet applied.

Example

curl "https://moda.dev/api/v1/data/problems?days_back=30&limit=1" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "summary": {
    "days_back": 30,
    "open_problems": 6,
    "reopened": 1,
    "total_problems": 8,
    "signals_attributed": 412,
    "explained_coverage_pct": 71.4
  },
  "remainder": {
    "attributed_signals": 412,
    "unexplained_signals": 165,
    "coverage_pct": 71.4,
    "historically_attributed_signals": 447,
    "historical_coverage_pct": 77.5
  },
  "problems": [
    {
      "problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
      "display_name": "Ticket creation fails on urgent priority",
      "cause_statement": "The create_ticket tool is called with priority values the ticketing API rejects, so refund escalations silently fail.",
      "lifecycle": "open",
      "rank_score": 0.92,
      "rubric_version": 4,
      "total_attributions": 61,
      "family_weighted_count": 48.5,
      "affected_users": 37,
      "affected_conversations": 44,
      "agg_prm_delta": -0.18,
      "abandonment_rate": 0.27,
      "recency_score": 0.81,
      "trend_score": 0.34,
      "multi_family": true,
      "family_counts": { "tool_failure": 42, "emotion": 19 },
      "coverage_overall": 0.71,
      "coverage_by_family": { "tool_failure": 0.84, "emotion": 0.52 },
      "audit_pass_rate": 0.93,
      "verification_status": "current",
      "verified_causal_version": 3
    }
  ],
  "untrusted": [],
  "hierarchy": {
    "macros": [
      {
        "problem_id": "9a2e7c14-5b3f-4d80-a6e1-2f7b8c9d0e13",
        "display_name": "Ticketing integration reliability",
        "display_description": "Failures and workarounds in the ticketing tool chain.",
        "tier": "macro",
        "child_count": 2,
        "children": ["3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21", "b4c8d1e6-0f2a-4357-9b8c-7d6e5f4a3b2c"]
      }
    ],
    "unparented_leaf_count": 3
  },
  "emerging": [],
  "freshness": {
    "book_computed_at": "2026-08-14T03:12:44",
    "latest_assignment_at": "2026-08-14T11:05:09",
    "lag_seconds": 28345,
    "discovery": {
      "latest_session_ts": "2026-08-14T03:10:02",
      "groups_total": 21,
      "groups_processed": 18,
      "groups_skipped": 3,
      "saturation": false,
      "stop_reason": "exhausted"
    },
    "verification": { "live_total": 8, "current": 6, "stale": 1, "failed": 0, "unverified": 1 },
    "remainder_backlog": { "pending_groups": 3, "pending_mass": 41 }
  },
  "feedback_pending": 1
}

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.

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

{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).

object

Verification confidence for the current problem version: current_rubric_version, causal_content_version, verification_status, audited_causal_content_version, per-version breakdowns (current, stale), and passed/failed samples.

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 conversations 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, verification} where story_kind is one of top_confidence, ground_truth_passed, disputed, replay_verified, newest.

Example

curl "https://moda.dev/api/v1/data/problems/3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "found": true,
  "problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "requested_problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "alias_resolved": false,
  "header": { "problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21", "display_name": "Ticket creation fails on urgent priority", "lifecycle": "open", "rank_score": 0.92, "verification_status": "current" },
  "rubric": {
    "version": 4,
    "cause_statement": "The create_ticket tool is called with priority values the ticketing API rejects, so refund escalations silently fail.",
    "display_name": "Ticket creation fails on urgent priority",
    "display_description": "Escalations fail when the agent passes 'urgent' as a ticket priority.",
    "lifecycle": "open",
    "parent_problem_id": "9a2e7c14-5b3f-4d80-a6e1-2f7b8c9d0e13",
    "change_reason": "Narrowed match criteria after false positives on timeout errors.",
    "match_criteria": { "tool_name": "create_ticket", "error_pattern": "priority" },
    "counter_examples": [],
    "scope_hints": [],
    "updated_at": "2026-08-14T03:11:57",
    "tier": "leaf",
    "provisional": false,
    "affected_surface": "ticketing integration",
    "causal_content_version": 3
  },
  "trend": [
    { "run_ts": "2026-08-14T03:12:44", "rank_score": 0.92, "total_attributions": 61, "rubric_version": 4, "coverage_overall": 0.71 }
  ],
  "sub_problems": [],
  "verification": {
    "audit_pass_rate": 0.93,
    "judge_audit": { "passed": 14, "total": 15 },
    "counterfactual_replay": { "passed": 4, "total": 4 },
    "samples": []
  },
  "evidence": [
    {
      "attribution_id": "e19c3d47-8a2b-4f60-95c1-3d2e1f0a9b87",
      "conversation_id": "conv_9f2c41d08ab37e51",
      "segment_id": "c7e5a1d2-4f6b-5a38-9c21-8b0e3d47f6a9",
      "anchor_signal_id": "8c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "anchor_msg_index": 7,
      "signal_family": "tool_failure",
      "signal_type": "validation_error",
      "confidence": 0.9,
      "causal_rationale": "The failure occurs on every escalation where the agent sets priority to 'urgent'.",
      "door": "rubric_match",
      "replay_verified": true,
      "evidence_snippet": "{\"excerpt\":\"create_ticket failed: 422 Unprocessable Entity\",\"families\":[\"tool_failure\"],\"line\":\"priority must be one of low, normal, high\",\"anchor\":{\"family\":\"tool_failure\",\"type\":\"validation_error\",\"msg_index\":7},\"door\":\"rubric_match\",\"mechanism\":\"invalid enum value\"}",
      "dedup_count": 1,
      "user_id": "user_4821",
      "assigned_at": "2026-08-14T09:52:30",
      "snippet_parsed": {
        "excerpt": "create_ticket failed: 422 Unprocessable Entity",
        "families": ["tool_failure"],
        "line": "priority must be one of low, normal, high",
        "anchor": { "family": "tool_failure", "type": "validation_error", "msg_index": 7 },
        "door": "rubric_match",
        "mechanism": "invalid enum value"
      },
      "snippet_legacy_raw_text": false,
      "report_id": "a7b6c5d4-e3f2-4109-8765-4321fedcba98"
    }
  ],
  "affected_conversations": [
    { "conversation_id": "conv_9f2c41d08ab37e51", "user_id": "user_4821", "signal_count": 3, "family_counts": { "tool_failure": 2, "emotion": 1 }, "last_signal_at": "2026-08-14T09:52:30" }
  ],
  "remainder": { "attributed_signals": 412, "unexplained_signals": 165, "coverage_pct": 71.4, "historically_attributed_signals": 447, "historical_coverage_pct": 77.5 },
  "investigation_reports": { "items": [], "has_more": true, "next_cursor": "eyJ0cyI6IjIwMjYtMDgtMTMifQ" },
  "confidence": {
    "current_rubric_version": 4,
    "causal_content_version": 3,
    "verification_status": "current",
    "audited_causal_content_version": 3,
    "current": { "causal_content_version": 3, "kinds": { "judge_audit": { "pass_rate": 0.93, "n": 15, "latest_ts": "2026-08-14T03:12:01" }, "ground_truth": null, "counterfactual_replay": { "pass_rate": 1, "n": 4, "latest_ts": "2026-08-14T03:12:20" } } },
    "stale": null,
    "samples": { "passed": [], "failed": [] }
  },
  "change_history": [],
  "impact_identity": { "known_users": 37, "unknown_identity_conversations": 5, "total_conversations": 44, "identity_coverage_pct": 88.6 },
  "hierarchy": { "tier": "leaf", "parent": { "problem_id": "9a2e7c14-5b3f-4d80-a6e1-2f7b8c9d0e13", "display_name": "Ticketing integration reliability", "tier": "macro" }, "children": [] },
  "dossier": null,
  "stories": []
}

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.

curl "https://moda.dev/api/v1/data/problems/3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21/reports?limit=1" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "requested_problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "reports": [
    {
      "report_id": "a7b6c5d4-e3f2-4109-8765-4321fedcba98",
      "conversation_id": "conv_9f2c41d08ab37e51",
      "segment_id": "c7e5a1d2-4f6b-5a38-9c21-8b0e3d47f6a9",
      "status": "investigated",
      "problem_found": true,
      "mechanism": "create_ticket rejects the 'urgent' priority enum; the agent never surfaces the error to the user.",
      "narrative": "The user asked for an escalation. The agent called create_ticket with priority 'urgent', which the ticketing API rejects with a 422. The agent then told the user the ticket was created.",
      "citations": [
        { "path": "conversation", "ref": "msg 7", "quote": "422 Unprocessable Entity: field 'priority' must be one of low, normal, high" }
      ],
      "signals_explained": 2,
      "signals_total": 3,
      "signals_explained_ids": ["8c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f"],
      "signals_unexplained_ids": ["1f2e3d4c-5b6a-7980-1234-56789abcdef0"],
      "suspected_surface": "ticketing integration",
      "severity": "high",
      "confidence": 0.88,
      "primary_family": "tool_failure",
      "investigated_at": "2026-08-14T02:58:41"
    }
  ],
  "pagination": { "limit": 1, "has_more": true, "next_cursor": "eyJ0cyI6IjIwMjYtMDgtMTMifQ" }
}

GET /problems/:id/conversations

Conversations attributed to one problem, keyset-paginated, with per-conversation 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 conversation joined the problem: rubric_match or local_causal_chain.

curl "https://moda.dev/api/v1/data/problems/3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21/conversations?limit=1" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "requested_problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "family": null,
  "door": null,
  "conversations": [
    {
      "conversation_id": "conv_9f2c41d08ab37e51",
      "user_id": "user_4821",
      "attribution_count": 3,
      "families": { "tool_failure": 2, "emotion": 1 },
      "first_anchor_at": "2026-08-14T09:31:41",
      "last_anchor_at": "2026-08-14T09:52:30",
      "latest_anchor": {
        "segment_id": "c7e5a1d2-4f6b-5a38-9c21-8b0e3d47f6a9",
        "anchor_signal_id": "8c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
        "anchor_msg_index": 7
      }
    }
  ],
  "pagination": { "limit": 1, "has_more": true, "next_cursor": "eyJ0cyI6IjIwMjYtMDgtMTQifQ" }
}

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.

curl "https://moda.dev/api/v1/data/problems/3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21/evidence?limit=25" \
  -H "x-api-key: YOUR_MODA_API_KEY"

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 problem-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.

curl -X POST "https://moda.dev/api/v1/data/problems/3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21/feedback" \
  -H "x-api-key: YOUR_MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "mark_fixed", "reason": "Priority enum fixed in ticketing client v2.4.1", "actor": "release-bot"}'

{
  "success": true,
  "feedback_id": "c2d4e6f8-0a1b-4c3d-9e8f-7a6b5c4d3e2f",
  "problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "action": "mark_fixed",
  "status": "pending",
  "duplicate": false
}

A malformed (non-UUID) problem ID returns 400.

GET /problems/:id/feedback

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

curl "https://moda.dev/api/v1/data/problems/3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21/feedback" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "requested_problem_id": "3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21",
  "feedback": [
    {
      "feedback_id": "c2d4e6f8-0a1b-4c3d-9e8f-7a6b5c4d3e2f",
      "feedback_kind": "mark_fixed",
      "reason": "Priority enum fixed in ticketing client v2.4.1",
      "attribution_id": null,
      "new_display_name": "",
      "actor": "release-bot",
      "status": "pending",
      "consumed_by_run_id": null,
      "created_at": "2026-08-14T12:02:19.000Z"
    }
  ],
  "pending_count": 1
}

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 problem-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, other.

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.

curl -X POST "https://moda.dev/api/v1/data/feedback" \
  -H "x-api-key: YOUR_MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "bad_cluster_label",
    "severity": "low",
    "note": "Cluster node_47 is labeled Refund requests but contains mostly invoice questions.",
    "source": "sdk",
    "refs": { "cluster_id": "node_47" }
  }'

{
  "feedback_id": "f0e1d2c3-b4a5-4968-8776-5544332211aa",
  "submitted_at": "2026-08-14 12:05:31.482"
}

Next steps

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

​GET /problems

​Query parameters

​Response fields

​Example

​GET /problems/:id

​Response fields

​Example

​GET /problems/:id/reports

​Query parameters

​GET /problems/:id/conversations

​Query parameters

​GET /problems/:id/evidence

​Query parameters

​POST /problems/:id/feedback

​Body fields

​GET /problems/:id/feedback

​POST /feedback

​Body fields

​Next steps

GET /problems

Query parameters

Response fields

Example

GET /problems/:id

Response fields

Example

GET /problems/:id/reports

Query parameters

GET /problems/:id/conversations

Query parameters

GET /problems/:id/evidence

Query parameters

POST /problems/:id/feedback

Body fields

GET /problems/:id/feedback

POST /feedback

Body fields

Next steps