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

# Query MCP usage insights over the Armature REST API

> Pull MCP analytics — overview KPIs, topics, failed search clusters, and session traces — into BI tools, alerting, or your own dashboards.

The `/insights` endpoints expose Armature's MCP usage analytics: how agents are using your MCP source, which intents recur, where searches fail, and what individual sessions did. Use them to feed BI dashboards, build custom alerts on unmet demand, or export session traces to your own data store.

All paths are relative to the [REST API base URL](/rest-api/overview#base-url). All requests require an [API key](/rest-api/authentication).

<Note>
  Insights endpoints require MCP Analytics to be enabled for your organization. Requests against a disabled organization return `403` with `error.code = feature_disabled`.
</Note>

## Overview KPIs

```http theme={null}
GET /insights/overview
```

Returns the headline KPIs, trend lines, top topics, and top failed-search clusters for the selected window.

| Query parameter | Description                                     |
| --------------- | ----------------------------------------------- |
| `range`         | `24h`, `7d`, `30d`, or `90d`. Defaults to `7d`. |

```bash theme={null}
curl "https://your-org.armature.app/api/armature/v1/insights/overview?range=7d" \
  -H "Authorization: Bearer amt_<key-id>_<secret>"
```

## List topics

```http theme={null}
GET /insights/topics
```

Lists recurring MCP usage topics and unmet-demand groups.

| Query parameter | Description                                     |
| --------------- | ----------------------------------------------- |
| `range`         | `24h`, `7d`, `30d`, or `90d`. Defaults to `7d`. |
| `sort`          | `volume`, `frustration`, or `trend`.            |
| `limit`         | Maximum topics to return.                       |

## Get a topic

```http theme={null}
GET /insights/topics/{id}
```

Returns the topic record with sample sessions and related failed searches.

## Update a topic

```http theme={null}
PATCH /insights/topics/{id}
```

Rename a topic, flag it as unmet demand, or archive it. Requires `editor`, `admin`, or `owner`.

**Request body**

| Field             | Type    | Description                     |
| ----------------- | ------- | ------------------------------- |
| `label`           | string  | New display label.              |
| `is_unmet_demand` | boolean | Flag the topic as unmet demand. |
| `archived`        | boolean | Archive or unarchive the topic. |

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/insights/topics/{id} \
  -X PATCH \
  -H "Authorization: Bearer amt_<key-id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{ "is_unmet_demand": true }'
```

## List failed searches

```http theme={null}
GET /insights/searches
```

Lists failed SDK searches and suggested API gaps.

| Query parameter | Description                                     |
| --------------- | ----------------------------------------------- |
| `range`         | `24h`, `7d`, `30d`, or `90d`. Defaults to `7d`. |
| `limit`         | Maximum clusters to return.                     |

## Get a failed search cluster

```http theme={null}
GET /insights/searches/{id}
```

Returns the cluster detail and a sample of sessions where the search appeared.

## List sessions

```http theme={null}
GET /insights/sessions
```

Lists MCP analytics sessions for the selected window.

| Query parameter | Description                                        |
| --------------- | -------------------------------------------------- |
| `range`         | `24h`, `7d`, `30d`, or `90d`. Defaults to `7d`.    |
| `view`          | `all`, `high_frustration`, `repeat`, or `flagged`. |
| `intent`        | Filter by raw intent label.                        |
| `search_miss`   | Filter by exact failed-search text.                |
| `limit`         | Maximum sessions to return.                        |

```bash theme={null}
curl "https://your-org.armature.app/api/armature/v1/insights/sessions?view=high_frustration&range=7d" \
  -H "Authorization: Bearer amt_<key-id>_<secret>"
```

## Get a session trace

```http theme={null}
GET /insights/sessions/{id}/trace
```

Returns the full session trace — events, tool calls, searches, logs, and classifications. Use this to drill into a specific session surfaced by the overview, topics, or sessions list.

## Related

* [REST API overview](/rest-api/overview)
* [Authentication](/rest-api/authentication) — feature-gated endpoints and the `feature_disabled` error.