GET /overview
Headline KPIs for a window, plus top clusters and recent activity.Query parameters
1–90. Applies to the trace, frustration, and tool-failure KPIs, and to recent activity.
Response fields
Trace counts:
total in the window and trend_pct — percentage change versus the previous window of equal length (one decimal; 0 when the previous window was empty).Up to 10 clusters from the latest clustering run, largest first:
node_id, label, summary, keywords[], segment_count.Up to 10 most recent trace summaries updated within the last
days_back days (7 by default): conversation_id, summary, timestamp. The window and timestamp use the rollup’s updated_at time.Example
GET /trends
The dashboard’s KPIs for a window against the window of equal length just before it, from the same loaders as the Analytics overview, the Signals rate cards, the detector KPI tiles and the Problems trend card. Withsince set to a deploy time, the response compares the time since the deploy with the same length of time before it. moda overview --compare and moda detections list --compare read this endpoint.
Query parameters
Response fields
Every figure is{ current, previous, delta, delta_pct, spike? }. delta is current minus previous (percentage points for a _pct rate), delta_pct the relative change in percent, and spike (present only when true) the dashboard’s spike rule.
Example
GET /clusters
Browses the hierarchical use-case clusters from the latest completed clustering run. Call it without parameters for the root level; pass a node’snode_id as parent_id to descend.
Query parameters
Return the children of this node. Omit for root-level nodes. The response’s
breadcrumb traces the path from the root to this node.One of
all, 1h, 24h, 3d, 7d, 30d, 90d. The hierarchy always comes from the latest clustering run. With a window other than all, each node’s segment_count counts only the run’s segments whose trace was last active in the window, nodes with no such segments are left out, and meta counts the window.builtin:<key> or a saved cohort id: only the nodes the cohort’s users reach, each segment_count the cohort’s segments over the Topics tree window (time_range must be all, 3d, 7d or 30d), as the dashboard Topics page counts a cohort. meta.cohort_clusters and meta.cohort_segments describe this level; total_clusters and total_segments stay the whole run. 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
The latest completed run:
id, num_categories, num_clusters, num_segments, completed_at. null when no taxonomy exists yet — the first one is built once at least 50 analyzed segments exist. Always describes the whole run, whatever time_range is.Child nodes ordered by size:
node_id, label, summary, keywords[], node_type, segment_count, has_children, depth.total_clusters (nodes of type cluster; categories are not counted) and total_segments (each segment counted once), plus time_range and windowed. With time_range=all they match cluster_run.num_clusters and cluster_run.num_segments; with a window they count only clusters and segments in the window.Example
GET /clusters/:nodeId/conversations
Lists traces whose segments belong to one cluster node.An unknown
nodeId returns 200 with cluster: null and an empty conversations array — not 404. Check cluster before reading the list.Query parameters
Response fields
node_id, label, summary, segment_count — or null when the node does not exist in the latest run.Example
GET /task-clusters/search
Searches cluster nodes in the latest hierarchy by name or meaning. Use it to resolve a phrase like “refund requests” to anode_id you can pass to /clusters/:nodeId/conversations or the cluster_id filter on /conversations.
Query parameters
Deterministic lookup of one node (returns that node with its ancestor path). Makes
q optional.builtin:<key> or a saved cohort id. Only nodes reached by the cohort’s users are searched (before ranking and limit), and each match’s segment_count counts the cohort’s segments. With node_id, a node the cohort does not reach returns no match. The cohort’s membership is refreshed first when it is missing or stale; an unknown saved cohort id returns 404.With
cohort: the window the cohort’s topics and counts cover, matching the Topics tree. One of all, 3d, 7d, 30d. A topic the cohort reached only outside the window is not returned.Response fields
The run the matches came from.
null (with empty matches) when no clustering run exists yet.The mode that actually served the request. Falls back to
fuzzy when semantic search is unavailable.Each match has
node_id, parent_id, depth, node_type, label, description, keywords[], segment_count, ancestor_path[] ({nodeId, label, depth} from the root), path_truncated, and similarity (semantic/hybrid matches only).Example
Next steps
- Traces — filter the trace list by
cluster_id. - Dashboard: Clusters — the same hierarchy in the dashboard, including how the taxonomy is built.
- Problems — ranked root-cause problems across signals.