> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Problems

> GET /problems for the ranked root-cause list, per-problem detail and evidence, and the feedback endpoints that steer discovery.

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](https://docs.moda.dev/dashboard/problems.md) 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](#get-problemsdream).

### Query parameters

**days\_back** `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.

**limit** `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`).

**offset** `integer` (default: 0)

Row to start each partition at: `next_offset` of the previous page.

**list\_version** `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`.

**sort** `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.

**dir** `string` (default: desc)

`desc` or `asc`, for a `sort` other than `rank`.

**cohort** `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

**summary** `object`

`days_back`, `window_hours` (dream-grouped tenants only), `open_problems`, `reopened`, `total_problems`, `signals_attributed`, `explained_coverage_pct`.

**remainder** `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`.

**problems** `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.

**untrusted** `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.

**next\_offset** `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.

**hierarchy** `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`.

**emerging** `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`.

**emerging\_total** `integer`

How many provisional problems there are in all; more than the length of `emerging` when `limit` cut it.

**freshness** `object`

When things were last computed: `book_computed_at`, `latest_assignment_at`, `lag_seconds`, `verification` (counts by status).

**feedback\_pending** `integer`

Feedback rows submitted but not yet applied.

**warnings** `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

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

```json theme={"dark"}
{
  "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,
    "unexplained_signals_scope": "current_plus_historical",
    "unexplained_signals_current": 130,
    "unexplained_signals_historical_only": 35,
    "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,
      "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,
    "verification": { "live_total": 8, "current": 6, "stale": 1, "failed": 0, "unverified": 1 }
  },
  "feedback_pending": 1,
  "warnings": []
}
```

> [!NOTE]
>
> 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](#get-problems), as on the dashboard.

### Query parameters

**days\_back** `integer`

1–90 days ending now. Absent: the dream run's whole window, the dashboard's default.

**limit** `integer` (default: 25)

1–200 problems per page.

**offset** `integer` (default: 0)

`next_offset` of the previous page. Pass `list_version` with it.

**list\_version** `string`

`list_version` of the first page; a later page is cut from the same read while it is cached (5 minutes).

**sort** `string` (default: severity)

`severity` (the dream's rank), `users`, or `silent` (share of users who never noticed): the dashboard table's columns.

**dir** `string` (default: desc)

`desc` or `asc`.

**cohort** `string`

`builtin:<key>` or a saved cohort id: every count comes from the cohort's users.

### Response fields

**available** `boolean`

`true` when the tenant has a dream grouping published (the dashboard then shows it).

**run** `object`

The dream run the list comes from: `run_id`, `window_end`, `window_hours`, `incidents`, `unsorted`, `users`, `users_grouped`.

**summary** `object`

`problems` (every problem the table shows), `incidents`, `unsorted_incidents`, `users`, `users_grouped`, `pinned_problem_ids`, and `previous` (the window before, with `comparable`).

**problems** `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`.

**worst\_incidents** `array`

First page only: the most severe rated incidents of the shown problems.

**next\_offset** `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.

**limit** `integer` (default: 5)

1–50 incidents per page. `incidents_total` counts them all; `next_offset` starts the next page.

**offset** `integer` (default: 0)

First incident to return.

**days\_back** `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

**found** `boolean`

`false` when the ID does not resolve to a problem; all other blocks are then empty or `null`.

**problem\_id / requested\_problem\_id / alias\_resolved** `string / string / boolean`

The surviving problem ID, the ID you requested, and whether a merged-away ID was folded to its survivor.

**header** `object | null`

The same row shape as the list on `GET /problems`.

**rubric** `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`.

**trend** `array`

Rank history: `{run_ts, rank_score, total_attributions, rubric_version, coverage_overall}` per computation run, newest first.

**sub\_problems** `array`

Child problems for macro problems: `{problem_id, display_name, cause_statement, lifecycle, version}`.

**verification** `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`.

**evidence** `array`

A first page of evidence rows (see [`/problems/:id/evidence`](#get-problemsidevidence) for the full paginated set and field list).

**affected\_conversations** `array`

Per-trace `{conversation_id, user_id, signal_count, family_counts, last_signal_at}` rollups.

**remainder** `object`

The same tenant-wide coverage meter as the list endpoint.

**investigation\_reports** `object`

First page of investigation reports: `{items[], has_more, next_cursor}` (full set on [`/problems/:id/reports`](#get-problemsidreports)).

**change\_history** `array`

Lineage events: `{problem_id, event_id, event_kind, related_problem_id, rubric_version, causal_content_version, reason, created_ts}`.

**impact\_identity** `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.

**hierarchy** `object`

`tier`, `parent` (or `null`), `children[]`.

**dossier** `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.

**stories** `array`

Representative examples, each `{story_kind, evidence}` where `story_kind` is one of `top_confidence`, `replay_verified`, `newest`.

### Example

```bash theme={"dark"}
curl "https://moda.dev/api/v1/data/problems/3f6b0a52-9d1c-4e7a-b2f8-6c0d5e4a3b21" \
  -H "x-api-key: YOUR_MODA_API_KEY"
```

```json theme={"dark"}
{
  "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, "unexplained_signals_scope": "current_plus_historical", "unexplained_signals_current": 130, "unexplained_signals_historical_only": 35, "coverage_pct": 71.4, "historically_attributed_signals": 447, "historical_coverage_pct": 77.5 },
  "investigation_reports": { "items": [], "has_more": true, "next_cursor": "eyJ0cyI6IjIwMjYtMDgtMTMifQ" },
  "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": []
}
```

> [!NOTE]
>
> 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

**limit** `integer` (default: 20)

1–50.

**cursor** `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`.

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

```json theme={"dark"}
{
  "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

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

### Query parameters

**limit** `integer` (default: 25)

1–50.

**cursor** `string`

The `next_cursor` from a previous page.

**family** `string`

Filter to one signal family (for example `tool_failure`, `emotion`).

**door** `string`

How the trace joined the problem: `rubric_match` or `local_causal_chain`.

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

```json theme={"dark"}
{
  "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`](https://docs.moda.dev/data-api/traces#get-conversationsidcontext) 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

**limit** `integer` (default: 25)

1–50.

**cursor** `string`

The `next_cursor` from a previous page.

```bash theme={"dark"}
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 problems feedback`.

### Body fields

**action** `string` *required*

One of `mark_fixed`, `dismiss`, `flag_attribution`, `rename`.

**reason** `string`

Up to 2,000 characters. **Required** for `dismiss` and `flag_attribution`.

**attribution\_id** `string`

**Required** for `flag_attribution`. A non-UUID value returns `400`; a UUID that does not belong to this problem returns `404`.

**new\_display\_name** `string`

Up to 255 characters. **Required** for `rename`.

**actor** `string` (default: data-api)

Recorded as the acting identity, up to 255 characters.

> [!NOTE]
>
> 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.

```bash theme={"dark"}
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"}'
```

```json theme={"dark"}
{
  "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/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.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | 30 | Days of history (1–90). `compare` is `null` above 45 days because the history keeps 90 days. |

| Field | Description |
| - | - |
| `problem_id`, `requested_problem_id` | The problem the history is for, and the id asked for. |
| `first_seen`, `last_seen` | First and last day the problem held an incident, over all its history. |
| `compare` | `incidents` and `signals`: `{ current, previous, delta, delta_pct }`. |
| `series` | `incidents` and `users` as `[date, value]` arrays, oldest first. `users` are distinct per day; do not sum them. |

## GET /problems/:id/feedback

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

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

```json theme={"dark"}
{
  "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](#post-problemsidfeedback) (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

**category** `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`.

**severity** `string` (default: low)

One of `info`, `low`, `medium`, `high`.

**note** `string`

Up to 4,000 characters describing what looked wrong.

**source** `string`

One of `cli`, `sdk`, `ui`.

**agent** `string`

The agent submitting the feedback, up to 64 characters.

**cli\_version** `string`

Up to 32 characters.

**refs** `object`

Free-form references, for example `{"conversation_id": "...", "tool_name": "..."}`.

**command\_context** `object`

Free-form context about the command or query that produced the suspect result.

> [!WARNING]
>
> 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.

```bash theme={"dark"}
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" }
  }'
```

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

## Next steps

* [Dashboard: Problems](https://docs.moda.dev/dashboard/problems.md) — the same problem book as a kanban with dossiers.
* [Signals](https://docs.moda.dev/data-api/signals.md) — the raw detections that problems are built from.
* [Traces](https://docs.moda.dev/data-api/traces.md) — 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.

| Parameter | Values |
| - | - |
| `nodeId` | A use-case node, including its descendants |
| `problemId` | A problem UUID; merges resolve to the current problem |
| `mode` | `metrics` (default), `trend`, `evidence`, `catalog`, `overview`, `affected-use-cases`, or `trace-use-cases` |
| `days` | `1`, `3`, `7` (default), `30`, `90`, or `all` |
| `to` | Optional UTC ISO timestamp with milliseconds; fixes the window end |
| `runId` | Optional expected classification run; mismatch returns `409` |
| `cursor` | Opaque continuation returned by `evidence`; retain the same scope |
| `conversationIds` | JSON array of 1–25 trace IDs for `trace-use-cases`; requires `problemId` |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.