Skip to main content
These are the Traces endpoints. They read individual traces: list and filter them, pull a window of messages around a specific turn, and inspect a trace’s world state. Endpoint paths and field names keep 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).
string
Restrict to traces assigned to one use-case cluster node (see Analytics).
string
Restrict to traces from one end user.
string
default:"all"
One of all, 1h, 24h, 3d, 7d, 30d, 90d. Filters on the trace’s last activity.
string
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.
string
Absolute end, inclusive; a date-only value covers that whole UTC day. Must not precede since; at most 366 days apart.
string
default:"all"
One of all, development, staging, production.
string
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.
string
default:"any"
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.
string
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.
integer
default:"20"
1–100.
integer
default:"0"
0–10,000.

Response fields

array
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.
string
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.
object
limit, offset, total, has_more.
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

integer
Zero-based index of the center message. Defaults to the middle of the trace. Out-of-range values are clamped to the last message.
integer
default:"2"
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.
string
1 (or true) returns only summary and total_messages, with an empty context.messages and metadata_only: true, without reading any message.

Response fields

string
integer
Total messages stored for the trace.
string
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.
object | null
The trace’s most recent open task, else its most recently updated task. Same shape as one entry of tasks.
integer
How many tasks the trace has.
array
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.
object
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 carries source: "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

string
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.
integer
Retired with the world-state event log: still accepted, and ignored.

Response fields

boolean
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.
string | null
The end user the trace belongs to, when known.
object | null
The user’s current cross-trace profile: slots (map of slot key to {value, source, ...}), updatedAt, slotCount.
object | null
The durable facts the trace started with, for a trace the task engine owns; null otherwise.
string
task_engine when the task engine owns the trace; absent otherwise.
array
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).
object
segmentCount, and lastUpdatedAt: the latest task-engine pass, or the latest task update.

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 answers 410 Gone with a JSON body naming what replaces them:
Replay answers the same with 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.