Outcome
Read the selected workspace’s saved dashboard, alert, report and recent-update counts.
Before you start
- Verify the exact identity, environment and approved organization with topolo whoami before discovering this action.
- Inspect the credential-scoped action and canonical resource discovery. Examples use synthetic resources; replace their handles only with separately verified targets.
- Validate the complete input and review the action plan. Mutation and organization-inventory actions require explicit confirmation; a successful shape check does not prove a runtime grant.
- Select a granted workspace through topolo resources. The CLI/MCP supplies canonical resource headers; workspace identity is not an arbitrary payload field.
Discover the target
topolo whoami --json
topolo apps get topolo-insights --json
topolo actions get app_topolo_insights.widget.get --detail --json
topolo resources topolo-insights --json
Request
GET /api/widget · permission workspace:read · read without mutation confirmation.
Inspect schemas and test this action in the signed action console. The complete field schema is also available through CLI/MCP action discovery.
Effects and scope
- Returns canonical v3 insights.workspace-summary; it is an asset summary, not event volume, visitors or source count.
- The local builder reads the organization plus canonical workspace resource header. It does not run the grant resolver used by the other data routes. A local fixture with no workspace grant still returned a saved-dashboard count when its credential had workspace:read. This observed access gap is not an authorization rule or permission to use that workspace.
- The shared wrapper may attach workspace labels and refresh/cache metadata. Reading can attempt Nexus metering when configured; these fixtures disable Nexus and do not prove paid or hosted behavior.
Interpret the response
- Check appId app_topolo_insights, contractVersion 3.0.0 and widget id insights.workspace-summary. Resource type is workspace; optional resourceId comes from request context, not organization.id.
- Read dashboards, alerts, reports and updated asset metrics. Empty means no configured assets; it does not prove analytics activity is absent.
- Resolve the workspace with published resource discovery before calling. Never use the observed raw-header grant gap to bypass a resource refusal.
Worked requests and responses
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Successful and refused captures below are separate examples. A refused response is a boundary, not a successful task.
empty · success 1 · HTTP 200
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_empty. Fixture handles authorize no live request.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_insights.widget.get --data @payload.json --json
topolo actions plan app_topolo_insights.widget.get --data @payload.json --json
topolo actions call app_topolo_insights.widget.get --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.widget.get",
"input": {}
}
}
Captured raw Worker result
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_insights",
"serviceName": "Insights",
"generatedAt": "2026-10-04T08:52:48.025Z",
"widgets": [
{
"id": "insights.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Insights workspace",
"description": "No dashboards, alerts, or reports configured yet in Insights.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_insights_empty",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "empty",
"observedAt": "2026-10-04T08:52:47.987Z",
"code": "no_analytics_activity",
"message": "No dashboards, alerts, or reports configured yet in Insights."
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [
{
"id": "overview",
"label": "Open Insights overview",
"href": "/dashboard/overview"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "insights.widget.title",
"descriptionKey": "insights.widget.summary"
},
"accessibility": {
"label": "Insights workspace metrics",
"description": "No dashboards, alerts, or reports configured yet in Insights."
},
"contribution": {
"summary": "Saved dashboards, alerts, reports, and recent updates for the selected Insights workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Insights workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "dashboards",
"label": "Dashboards",
"description": "Saved dashboards.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "alerts",
"label": "Alerts",
"description": "Configured alerts.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "reports",
"label": "Reports",
"description": "Configured reports.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "updated",
"label": "Updated",
"description": "Dashboards, alerts, and reports updated in the last 24 hours.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [],
"events": [
{
"key": "insight_updated",
"label": "Insight updated",
"description": "A dashboard, alert, or report was updated."
}
],
"datasets": [
{
"id": "insights_assets",
"label": "Insights assets",
"description": "Workspace analytics asset totals.",
"grain": "One aggregate row per selected Insights workspace.",
"metricKeys": [
"dashboards",
"alerts",
"reports",
"updated"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [
"insight_updated"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "dashboards",
"label": "Dashboards",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:47.987Z",
"end": "2026-10-04T08:52:47.987Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "alerts",
"label": "Alerts",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:47.987Z",
"end": "2026-10-04T08:52:47.987Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "reports",
"label": "Reports",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:47.987Z",
"end": "2026-10-04T08:52:47.987Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "updated",
"label": "Updated",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T08:52:47.987Z",
"end": "2026-10-04T08:52:47.987Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_insights",
"serviceName": "Insights",
"lastUpdated": "2026-10-04T08:52:48.025Z"
}
]
}
HTTP 200. Check appId app_topolo_insights, contractVersion 3.0.0 and widget id insights.workspace-summary. Resource type is workspace; optional resourceId comes from request context, not organization.id. Read dashboards, alerts, reports and updated asset metrics. Empty means no configured assets; it does not prove analytics activity is absent. Resolve the workspace with published resource discovery before calling. Never use the observed raw-header grant gap to bypass a resource refusal.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
workflow · success 2 · HTTP 200
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_insights.widget.get --data @payload.json --json
topolo actions plan app_topolo_insights.widget.get --data @payload.json --json
topolo actions call app_topolo_insights.widget.get --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.widget.get",
"input": {}
}
}
Captured raw Worker result
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_insights",
"serviceName": "Insights",
"generatedAt": "2026-10-04T08:52:48.464Z",
"widgets": [
{
"id": "insights.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Insights workspace",
"description": "No dashboards, alerts, or reports configured yet in Insights.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_insights_workflow",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T08:52:48.453Z",
"lastSuccessfulAt": "2026-10-04T08:52:48.453Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [
{
"id": "overview",
"label": "Open Insights overview",
"href": "/dashboard/overview"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "insights.widget.title",
"descriptionKey": "insights.widget.summary"
},
"accessibility": {
"label": "Insights workspace metrics",
"description": "No dashboards, alerts, or reports configured yet in Insights."
},
"contribution": {
"summary": "Saved dashboards, alerts, reports, and recent updates for the selected Insights workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Insights workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "dashboards",
"label": "Dashboards",
"description": "Saved dashboards.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "alerts",
"label": "Alerts",
"description": "Configured alerts.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "reports",
"label": "Reports",
"description": "Configured reports.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "updated",
"label": "Updated",
"description": "Dashboards, alerts, and reports updated in the last 24 hours.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [],
"events": [
{
"key": "insight_updated",
"label": "Insight updated",
"description": "A dashboard, alert, or report was updated."
}
],
"datasets": [
{
"id": "insights_assets",
"label": "Insights assets",
"description": "Workspace analytics asset totals.",
"grain": "One aggregate row per selected Insights workspace.",
"metricKeys": [
"dashboards",
"alerts",
"reports",
"updated"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [
"insight_updated"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "dashboards",
"label": "Dashboards",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:48.453Z",
"end": "2026-10-04T08:52:48.453Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "alerts",
"label": "Alerts",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:48.453Z",
"end": "2026-10-04T08:52:48.453Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "reports",
"label": "Reports",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:48.453Z",
"end": "2026-10-04T08:52:48.453Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "updated",
"label": "Updated",
"value": 1,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T08:52:48.453Z",
"end": "2026-10-04T08:52:48.453Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_insights",
"serviceName": "Insights",
"lastUpdated": "2026-10-04T08:52:48.464Z"
}
]
}
HTTP 200. Check appId app_topolo_insights, contractVersion 3.0.0 and widget id insights.workspace-summary. Resource type is workspace; optional resourceId comes from request context, not organization.id. Read dashboards, alerts, reports and updated asset metrics. Empty means no configured assets; it does not prove analytics activity is absent. Resolve the workspace with published resource discovery before calling. Never use the observed raw-header grant gap to bypass a resource refusal.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
grant-boundaries · success 3 · HTTP 200
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_merge. Fixture handles authorize no live request.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_insights.widget.get --data @payload.json --json
topolo actions plan app_topolo_insights.widget.get --data @payload.json --json
topolo actions call app_topolo_insights.widget.get --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.widget.get",
"input": {}
}
}
Captured raw Worker result
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_insights",
"serviceName": "Insights",
"generatedAt": "2026-10-04T08:52:49.330Z",
"widgets": [
{
"id": "insights.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Insights workspace",
"description": "No dashboards, alerts, or reports configured yet in Insights.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_insights_merge",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T08:52:49.320Z",
"lastSuccessfulAt": "2026-10-04T08:52:49.320Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [
{
"id": "overview",
"label": "Open Insights overview",
"href": "/dashboard/overview"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "insights.widget.title",
"descriptionKey": "insights.widget.summary"
},
"accessibility": {
"label": "Insights workspace metrics",
"description": "No dashboards, alerts, or reports configured yet in Insights."
},
"contribution": {
"summary": "Saved dashboards, alerts, reports, and recent updates for the selected Insights workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Insights workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "dashboards",
"label": "Dashboards",
"description": "Saved dashboards.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "alerts",
"label": "Alerts",
"description": "Configured alerts.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "reports",
"label": "Reports",
"description": "Configured reports.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "updated",
"label": "Updated",
"description": "Dashboards, alerts, and reports updated in the last 24 hours.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [],
"events": [
{
"key": "insight_updated",
"label": "Insight updated",
"description": "A dashboard, alert, or report was updated."
}
],
"datasets": [
{
"id": "insights_assets",
"label": "Insights assets",
"description": "Workspace analytics asset totals.",
"grain": "One aggregate row per selected Insights workspace.",
"metricKeys": [
"dashboards",
"alerts",
"reports",
"updated"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [
"insight_updated"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "dashboards",
"label": "Dashboards",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:49.320Z",
"end": "2026-10-04T08:52:49.320Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "alerts",
"label": "Alerts",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:49.320Z",
"end": "2026-10-04T08:52:49.320Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "reports",
"label": "Reports",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T08:52:49.320Z",
"end": "2026-10-04T08:52:49.320Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "updated",
"label": "Updated",
"value": 1,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T08:52:49.320Z",
"end": "2026-10-04T08:52:49.320Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_insights",
"serviceName": "Insights",
"lastUpdated": "2026-10-04T08:52:49.330Z"
}
]
}
HTTP 200. Check appId app_topolo_insights, contractVersion 3.0.0 and widget id insights.workspace-summary. Resource type is workspace; optional resourceId comes from request context, not organization.id. Read dashboards, alerts, reports and updated asset metrics. Empty means no configured assets; it does not prove analytics activity is absent. Resolve the workspace with published resource discovery before calling. Never use the observed raw-header grant gap to bypass a resource refusal.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
permission-refusals · refusal 4 · HTTP 403
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_merge. Fixture handles authorize no live request.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_insights.widget.get --data @payload.json --json
topolo actions plan app_topolo_insights.widget.get --data @payload.json --json
Captured raw Worker result
{
"success": false,
"error": {
"code": "action_permission_required",
"message": "Action \"widget.get\" requires permission \"workspace:read\".",
"action": "widget.get"
}
}
HTTP 403. The credential lacks the declared action permission. Inspect credential-scoped discovery in the same approved context; workspace role does not replace the permission.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
Verify the outcome
- Check appId app_topolo_insights, contractVersion 3.0.0 and widget id insights.workspace-summary. Resource type is workspace; optional resourceId comes from request context, not organization.id.
- Read dashboards, alerts, reports and updated asset metrics. Empty means no configured assets; it does not prove analytics activity is absent.
- Resolve the workspace with published resource discovery before calling. Never use the observed raw-header grant gap to bypass a resource refusal.
Errors and recovery
action_permission_required(HTTP 403): The credential lacks the declared action permission. Inspect credential-scoped discovery in the same approved context; workspace role does not replace the permission.
Only observed refusals are listed. This does not promise that external dependencies or every invalid payload have been exhaustively exercised.
Recovery boundary
This action does not change Insights records. Resolve the reported identity, permission, workspace or source problem in the approved context, then repeat the same read. A read result is not permission to modify its resources.
Related actions
- app_topolo_insights.dashboards.list: Read saved dashboard configuration and ordered widgets in the selected workspace.
- app_topolo_insights.analytics.overview: Read workspace-scoped analytics with a bounded time window, optional source and dimension drill-downs.
Evidence and limits
Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested.