conversation / conversation_id for backwards compatibility; a conversation_id value is the trace ID.
GET /conversations
Lists traces, newest first, with optional text search and structured filters.Query parameters
Free-text search over trace summaries and message bodies. When
search is the only filter, results may be relevance-ranked (see search_mode below).Restrict to traces assigned to one use-case cluster node (see Analytics).
Absolute start, inclusive: an ISO 8601 date or datetime, UTC unless an offset is given. With
since or until set, a trace is listed when it was active during the range: its first message is before the end and its last activity is at or after the start (intersected with time_range). With search, a trace is listed when a matching message falls inside the range.Absolute end, inclusive; a date-only value covers that whole UTC day. Must not precede
since; at most 366 days apart.Keyword(s) matched case-insensitively against the trace’s world state: the goals and summaries of its tasks and, for a trace the task engine owns, its facts and the user’s profile. Comma-separated terms are ANDed. Free text, not
key=value. Maximum 200 characters.any, positive, or negative, based on frustration detection. negative returns traces with a detected user frustration (detections whose every quote is marked a false positive are excluded); positive returns traces with none, including traces the frustration detector has not analyzed yet.builtin:<key> or a saved cohort id: only traces of the cohort’s current members, with the dashboard trace list’s own cohort scope. With search, the keyword path runs (no hybrid ranking). The cohort’s membership snapshot is refreshed first when it is missing or stale, as the dashboard does; an unknown saved cohort id returns 404, and the response echoes cohort.Response fields
One row per trace. Each row has
conversation_id (the trace ID), summary (its latest task’s goal, else its stored summary from before summaries were retired), message_count, first_timestamp, last_timestamp, duration_ms, cluster_id and cluster_name (or null), environment, latest_task, and task_count. latest_task is the trace’s most recent open task, else its most recently updated task (or null): thread_id, goal, status (active, resolved, cancelled, or stale for idle), latest_step, last_evidence_at, first_message_index, and last_message_index. With search_mode: hybrid, rows the semantic leg ranked by a task also carry matched_task (segment_id, thread_id, goal, status, similarity). duration_ms is the time from the first to the last message. It is null when the first or last timestamp is unknown: some imported traces store 1970-01-01T00:00:00, and replayed history stores placeholder timestamps before 2022 (such as 2020-01-01T00:00:00). sort_by=slowest orders by duration_ms and puts rows with unknown durations last.keyword or hybrid. hybrid runs only when search is set with no structured filters and semantic search is available; otherwise the deterministic keyword path serves the request.When
search_mode is hybrid, pagination.total is the size of the relevance-ranked candidate pool, not an exact corpus count. Branch on search_mode before treating total as an exact figure — in keyword mode it is exact.Example
GET /conversations/:id/context
Returns a window of parsed messages centered on one message index. Use it to read the turns around a search hit or a signal’s key turn.Query parameters
Zero-based index of the center message. Defaults to the middle of the trace. Out-of-range values are clamped to the last message.
Messages to include on each side of the center, 0–5 (larger values are clamped to 5).
0 returns only the center message, plus summary and total_messages.1 (or true) returns only summary and total_messages, with an empty context.messages and metadata_only: true, without reading any message.Response fields
One-line description of the trace: the goal of its latest task, else its stored summary from before conversation summaries were retired (they are no longer generated). Empty string when the trace has neither yet.
The trace’s most recent open task, else its most recently updated task. Same shape as one entry of
tasks.The trace’s tasks (world-state threads: one per thing the user asked for), open first, then most recently updated, up to 50. Each has
thread_id, goal, status (active, resolved, cancelled, or stale for idle), latest_step (the newest timeline entry), last_evidence_at, first_message_index, and last_message_index.center_index, from_index, to_index, and messages[]. Each message has index, role, content, tool_calls[] (id, name, input — input is a truncated string), tool_results[] (tool_use_id, content — truncated, is_error), and timestamp.Example
GET /conversations/:id/world-state
Returns the trace’s world state as it is now: its tasks (open and finished, each with a timeline; a subtask names its parent task), the facts recorded for it, and the end user’s durable cross-trace profile. This is the same data as the World State view on the trace detail page. There is no history of state changes. Tasks and facts come from the task engine for a trace it owns (the response then carriessource: "task_engine"), and from the task tracker otherwise. Task-tracker traces carry facts only where your workspace’s task records state them.
The world-state endpoints return camelCase field names (
hasData, segmentIndex, …), unlike the snake_case used by the rest of the Data API.Query parameters
Set to
1 to return segments as an empty array and add segmentSummaries — per-segment fact summaries (segmentIndex, durableCount, topSlots). Cheaper for a quick existence check.Response fields
false when no tasks or facts have been tracked for the trace yet. The response keeps its full shape (empty segments); an unknown trace ID answers the same way.The user’s current cross-trace profile:
slots (map of slot key to {value, source, ...}), updatedAt, slotCount.The durable facts the trace started with, for a trace the task engine owns;
null otherwise.The trace’s tasks and facts:
segmentIndex, segmentId, startMsgIdx, endMsgIdx, slots (facts), carryIn, openThreads[] (one per task, every status: id, status — open / resolved / cancelled / stale for idle, summary, goal, timeline[], subgoals[], and parent_id on a subtask), and slotCounts (durable, segmentLocal, total).Example
GET /conversations/:id/world-state/replay and /snapshot (retired)
Both are retired: they folded the world-state event log, which Moda no longer writes. Every request answers410 Gone with a JSON body naming what replaces them:
code: "world_state_replay_retired". Read the trace’s current tasks and facts with GET /conversations/:id/world-state, and what happened at a turn with GET /conversations/:id/context.
Next steps
- Search — find the message index to center a context window on.
- Data model — what traces, segments, slots, and threads mean.
- Dashboard: Traces — the same data in the Timeline and World State views.