Analytics

These endpoints read tenant-level aggregates: the headline KPIs shown on the dashboard home page and the hierarchical use-case clusters. New conversations 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 conversation, frustration, and tool-failure KPIs.

Response fields

object

{days} — the effective window.

object

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, tools.

array

Up to 10 clusters from the latest clustering run, largest first: node_id, label, summary, keywords[], segment_count.

array

The 10 most recent conversation summaries: conversation_id, summary, timestamp. Always covers the last 7 days, regardless of days_back.

Example

curl "https://moda.dev/api/v1/data/overview?days_back=30" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "period": { "days": 30 },
  "conversations": { "total": 5417, "trend_pct": 8.2 },
  "frustrations": { "total_analyzed": 4903, "frustrated": 171, "at_risk": 64, "rate_pct": 3.5 },
  "tool_failures": { "total": 240, "conversations": 188, "tools": 9 },
  "top_clusters": [
    { "node_id": "node_3", "label": "Billing and refunds", "summary": "Users ask about invoices, plan changes, and refunds.", "keywords": ["refund", "invoice", "billing"], "segment_count": 812 },
    { "node_id": "node_17", "label": "Integrations setup", "summary": "Users connect calendars, CRMs, and ticketing tools.", "keywords": ["oauth", "connect", "integration"], "segment_count": 655 }
  ],
  "recent_activity": [
    { "conversation_id": "conv_9f2c41d08ab37e51", "summary": "User asks how to request a refund for an annual plan; agent explains the policy and opens a ticket.", "timestamp": "2026-08-14T09:42:11" }
  ]
}

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"

Accepted and validated, but the hierarchy currently reflects the latest clustering run regardless of this value.

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.

{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 and total_segments for the whole run.

Example

curl "https://moda.dev/api/v1/data/clusters?parent_id=node_3" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "cluster_run": {
    "id": "v2_7f3d92e4-51b8-4c26-9a07-d1e5f2b8c634_20260809_020001_4e9a1c7b",
    "num_categories": 12,
    "num_clusters": 84,
    "num_segments": 10231,
    "completed_at": "2026-08-09T02:41:05"
  },
  "breadcrumb": [
    { "node_id": "node_3", "label": "Billing and refunds" }
  ],
  "clusters": [
    { "node_id": "node_47", "label": "Refund requests", "summary": "Users ask for full or partial refunds.", "keywords": ["refund", "money back"], "node_type": "cluster", "segment_count": 388, "has_children": false, "depth": 1 },
    { "node_id": "node_58", "label": "Invoice questions", "summary": "Users ask for invoices or billing history.", "keywords": ["invoice", "receipt"], "node_type": "cluster", "segment_count": 262, "has_children": false, "depth": 1 }
  ],
  "meta": { "total_clusters": 84, "total_segments": 10231 }
}

GET /clusters/:nodeId/conversations

Lists conversations 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

conversation_id, summary, message_count.

object

limit, offset, total, has_more.

Example

curl "https://moda.dev/api/v1/data/clusters/node_47/conversations?limit=2" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "cluster": {
    "node_id": "node_47",
    "label": "Refund requests",
    "summary": "Users ask for full or partial refunds.",
    "segment_count": 388
  },
  "conversations": [
    { "conversation_id": "conv_9f2c41d08ab37e51", "summary": "User asks how to request a refund for an annual plan; agent explains the policy and opens a ticket.", "message_count": 18 },
    { "conversation_id": "conv_77e0b3a94c12f8d6", "summary": "User requests a partial refund after downgrading mid-cycle.", "message_count": 9 }
  ],
  "pagination": { "limit": 2, "offset": 0, "total": 341, "has_more": true }
}

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.

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

curl "https://moda.dev/api/v1/data/task-clusters/search?q=refunds&limit=1" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "clusterRunId": "v2_7f3d92e4-51b8-4c26-9a07-d1e5f2b8c634_20260809_020001_4e9a1c7b",
  "query": "refunds",
  "search_mode": "hybrid",
  "matches": [
    {
      "node_id": "node_47",
      "parent_id": "node_3",
      "depth": 1,
      "node_type": "cluster",
      "label": "Refund requests",
      "description": "Users ask for full or partial refunds.",
      "keywords": ["refund", "money back"],
      "segment_count": 388,
      "ancestor_path": [
        { "nodeId": "node_3", "label": "Billing and refunds", "depth": 0 }
      ],
      "path_truncated": false,
      "similarity": 0.83
    }
  ]
}

Next steps

Conversations — filter the conversation list by cluster_id.
Dashboard: Use Cases — the same hierarchy in the dashboard, including how the taxonomy is built.
Problems — ranked root-cause problems across signals.

Data API

CLI

GET /overview

Query parameters

Response fields

Example

GET /clusters

Query parameters

Response fields

Example

GET /clusters/:nodeId/conversations

Query parameters

Response fields

Example

GET /task-clusters/search

Query parameters

Response fields

Example

Next steps

​GET /overview

​Query parameters

​Response fields

​Example

​GET /clusters

​Query parameters

​Response fields

​Example

​GET /clusters/:nodeId/conversations

​Query parameters

​Response fields

​Example

​GET /task-clusters/search

​Query parameters

​Response fields

​Example

​Next steps

GET /overview

Query parameters

Response fields

Example

GET /clusters

Query parameters

Response fields

Example

GET /clusters/:nodeId/conversations

Query parameters

Response fields

Example

GET /task-clusters/search

Query parameters

Response fields

Example

Next steps