> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> GET /overview for headline KPIs, /clusters for the use-case hierarchy, and /task-clusters/search for finding cluster nodes.

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

**days\_back** `integer` (default: 7)

1–90. Applies to the trace, frustration, and tool-failure KPIs, and to recent activity.

### Response fields

**period** `object`

`{days}` — the effective window.

**conversations** `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).

**frustrations** `object`

`total_analyzed`, `frustrated`, `at_risk` (risk score at least 0.5 but not frustrated), `rate_pct`.

**tool\_failures** `object`

`total` (failed calls), `conversations` (traces with a failure), `tools`.

**top\_clusters** `array`

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

**recent\_activity** `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

```bash theme={"dark"}
curl "https://moda.dev/api/v1/data/overview?days_back=30" \
  -H "x-api-key: YOUR_MODA_API_KEY"
```

```json theme={"dark"}
{
  "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 /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

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | 7 | Window ending now (1–90). Not with `since`/`until`. |
| `since` | string | — | Window start: ISO 8601 date or datetime, UTC unless an offset is given. |
| `until` | string | now | Window end, inclusive. Needs `since`. The window can span up to 90 days. |
| `agent` | string | — | One sub-agent name (from `agent.options`). Scopes the `overview` section only; `problems`, `rates` and `detectors` are left out because their loaders have no agent filter. Cannot be combined with `family`. |
| `unit` | string | `conversation` | Denominator of `rates`: `conversation`, `segment` or `turn`. |
| `include` | string | all | Comma-separated sections: `overview`, `problems`, `rates`, `detectors`. `problems` needs `days_back`. |
| `family` | string | — | One detector family (`emotion[:<f>]`, `frustration`, `tool_failure`, `laziness[:<f>]`, `hallucination`): only its detector KPIs and rate. `frustration` and sub-families return only that family's traces under `detectors` and leave out `rates`, whose cards count the whole detector. |
| `series` | string | `0` | `1`: add `series`, `[bucket, value]` arrays per hour (windows up to 2 days) or per day. |

### 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.

| Field | Description |
| - | - |
| `window` | `from`, `to`, `previous_from`, `previous_to`, `days`, `bucket` (`hour` or `day`). |
| `agent` | `selected` and `options` (`agent`, `label`, `conversations`), as the Analytics agent selector lists them. |
| `overview` | `conversations`, `messages`, `negative_emotion_rate_pct` (per analyzed trace), `tool_failure_rate_pct` (failed tool calls per call), `hallucinations` (a count of hallucinations: agent replies the conversation shows were false, never a rate); rates carry `of` and `n` (numerator and denominator per window). |
| `problems` | `window` (the loader's own bounds: its current window starts at a bucket boundary, so it can run longer than the previous one; a note gives both spans), `analysed_traces`, `traces_with_signal`, `signal_rate_pct` (the Problems trend card). |
| `rates` | `unit`, `units`, `comparable`, and `<detector>_pct` with `flagged` for emotion, tool\_failure, laziness, hallucination. When `comparable` is false (segment retention does not reach the previous window), `delta` and `delta_pct` are null. |
| `detectors` | KPI tiles per family: `emotion` (conversations\_analyzed, negative\_rate\_pct, negative\_detections, affected\_users, traces\_by\_family), `tool_failure` (failed\_traces, failures, failure\_rate\_pct, tool\_calls, users\_impacted, tools\_impacted), `laziness`, `hallucination`. |
| `series` | With `series=1`: `bucket`, then one `[bucket, value]` array per figure. |
| `notes` | Sections left out and why. |

### Example

```bash theme={"dark"}
curl "https://moda.dev/api/v1/data/trends?since=2026-10-17T14:00:00Z&include=overview,rates" \
  -H "x-api-key: $MODA_API_KEY"
```

```json theme={"dark"}
{
  "window": { "from": "2026-10-17T14:00:00.000Z", "to": "2026-10-18T14:00:00.000Z", "previous_from": "2026-10-16T14:00:00.000Z", "previous_to": "2026-10-17T14:00:00.000Z", "days": 1, "bucket": "hour" },
  "overview": {
    "conversations": { "current": 1104, "previous": 1180, "delta": -76, "delta_pct": -6.4 },
    "tool_failure_rate_pct": { "current": 1.31, "previous": 1.24, "delta": 0.07, "delta_pct": 5.4, "of": "tool receipts (one row per call)", "n": { "current": [173, 13243], "previous": [239, 19282] } }
  },
  "rates": { "unit": "conversation", "units": { "current": 1104, "previous": 1180, "delta": -76, "delta_pct": -6.4 }, "comparable": true, "emotion_pct": { "current": 32.1, "previous": 31.4, "delta": 0.7, "delta_pct": 2.4, "flagged": 354 } }
}
```

## 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

**parent\_id** `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.

**time\_range** `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.

**cohort** `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

**cluster\_run** `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.

**breadcrumb** `array`

`{node_id, label}` path from the root to `parent_id`. Empty when `parent_id` is omitted.

**clusters** `array`

Child nodes ordered by size: `node_id`, `label`, `summary`, `keywords[]`, `node_type`, `segment_count`, `has_children`, `depth`.

**meta** `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

```bash theme={"dark"}
curl "https://moda.dev/api/v1/data/clusters?parent_id=node_3" \
  -H "x-api-key: YOUR_MODA_API_KEY"
```

```json theme={"dark"}
{
  "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, "time_range": "all", "windowed": false }
}
```

## GET /clusters/:nodeId/conversations

Lists traces whose segments belong to one cluster node.

> [!NOTE]
>
> An unknown `nodeId` returns `200` with `cluster: null` and an empty `conversations` array — not `404`. Check `cluster` before reading the list.

### Query parameters

**limit** `integer` (default: 10)

1–100.

**offset** `integer` (default: 0)

0–10,000.

### Response fields

**cluster** `object | null`

`node_id`, `label`, `summary`, `segment_count` — or `null` when the node does not exist in the latest run.

**conversations** `array`

One row per trace: `conversation_id`, `summary`, `message_count`.

**pagination** `object`

`limit`, `offset`, `total`, `has_more`.

### Example

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

```json theme={"dark"}
{
  "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`](https://docs.moda.dev/data-api/traces).

### Query parameters

**q** `string`

Search text, 2–200 characters. Required unless `node_id` is given.

**node\_id** `string`

Deterministic lookup of one node (returns that node with its ancestor path). Makes `q` optional.

**mode** `string` (default: hybrid)

`fuzzy`, `semantic`, or `hybrid`.

**limit** `integer` (default: 30)

1–50.

**cohort** `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`.

**time\_range** `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

**clusterRunId** `string | null`

The run the matches came from. `null` (with empty `matches`) when no clustering run exists yet.

**search\_mode** `string`

The mode that actually served the request. Falls back to `fuzzy` when semantic search is unavailable.

**matches** `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

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

```json theme={"dark"}
{
  "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

* [Traces](https://docs.moda.dev/data-api/traces.md) — filter the trace list by `cluster_id`.
* [Dashboard: Clusters](https://docs.moda.dev/dashboard/use-cases.md) — the same hierarchy in the dashboard, including how the taxonomy is built.
* [Problems](https://docs.moda.dev/data-api/problems.md) — ranked root-cause problems across signals.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.