Skip to main content
These endpoints read tenant-level aggregates: the headline KPIs shown on the dashboard home page and the hierarchical use-case clusters. New traces are assigned to existing clusters continuously; the hierarchy itself is rebuilt automatically as traffic evolves, and new cluster nodes appear once a rebuild has run.

GET /overview

Headline KPIs for a window, plus top clusters and recent activity.

Query parameters

integer
default:"7"
1–90. Applies to the trace, frustration, and tool-failure KPIs, and to recent activity.

Response fields

object
{days} — the effective window.
object
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).
object
total_analyzed, frustrated, at_risk (risk score at least 0.5 but not frustrated), rate_pct.
object
total (failed calls), conversations (traces with a failure), tools.
array
Up to 10 clusters from the latest clustering run, largest first: node_id, label, summary, keywords[], segment_count.
array
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. With since 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’s node_id as parent_id to descend.

Query parameters

string
Return the children of this node. Omit for root-level nodes. The response’s breadcrumb traces the path from the root to this node.
string
default:"all"
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.
string
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

object | null
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.
array
{node_id, label} path from the root to parent_id. Empty when parent_id is omitted.
array
Child nodes ordered by size: node_id, label, summary, keywords[], node_type, segment_count, has_children, depth.
object
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

integer
default:"10"
1–100.
integer
default:"0"
0–10,000.

Response fields

object | null
node_id, label, summary, segment_count — or null when the node does not exist in the latest run.
array
One row per trace: conversation_id, summary, message_count.
object
limit, offset, total, has_more.

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 a node_id you can pass to /clusters/:nodeId/conversations or the cluster_id filter on /conversations.

Query parameters

string
Search text, 2–200 characters. Required unless node_id is given.
string
Deterministic lookup of one node (returns that node with its ancestor path). Makes q optional.
string
default:"hybrid"
fuzzy, semantic, or hybrid.
integer
default:"30"
1–50.
string
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.
string
default:"all"
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

string | null
The run the matches came from. null (with empty matches) when no clustering run exists yet.
string
The mode that actually served the request. Falls back to fuzzy when semantic search is unavailable.
array
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.