Skip to main content
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. All requests require an API key.
Insights endpoints require MCP Analytics to be enabled for your organization. Requests against a disabled organization return 403 with error.code = feature_disabled.

​
Overview KPIs

GET /insights/overview
Returns the headline KPIs, trend lines, top topics, and top failed-search clusters for the selected window.
Query parameterDescription
range24h, 7d, 30d, or 90d. Defaults to 7d.
curl "https://your-org.armature.app/api/armature/v1/insights/overview?range=7d" \
  -H "Authorization: Bearer amt_<key-id>_<secret>"

​
List topics

GET /insights/topics
Lists recurring MCP usage topics and unmet-demand groups.
Query parameterDescription
range24h, 7d, 30d, or 90d. Defaults to 7d.
sortvolume, frustration, or trend.
limitMaximum topics to return.

​
Get a topic

GET /insights/topics/{id}
Returns the topic record with sample sessions and related failed searches.

​
Update a topic

PATCH /insights/topics/{id}
Rename a topic, flag it as unmet demand, or archive it. Requires editor, admin, or owner. Request body
FieldTypeDescription
labelstringNew display label.
is_unmet_demandbooleanFlag the topic as unmet demand.
archivedbooleanArchive or unarchive the topic.
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

GET /insights/searches
Lists failed SDK searches and suggested API gaps.
Query parameterDescription
range24h, 7d, 30d, or 90d. Defaults to 7d.
limitMaximum clusters to return.

​
Get a failed search cluster

GET /insights/searches/{id}
Returns the cluster detail and a sample of sessions where the search appeared.

​
List sessions

GET /insights/sessions
Lists MCP analytics sessions for the selected window.
Query parameterDescription
range24h, 7d, 30d, or 90d. Defaults to 7d.
viewall, high_frustration, repeat, or flagged.
intentFilter by raw intent label.
search_missFilter by exact failed-search text.
limitMaximum sessions to return.
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

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.