Outcome
Read workspace-scoped analytics with a bounded time window, optional source and dimension drill-downs.
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.analytics.overview --detail --json
topolo resources topolo-insights --json
Request
GET /api/analytics/overview · 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
- Requires workspace read access. days is 1–90 with default 30; liveWindowMinutes is 5. Source is a registered machine key, not its id.
- Recognized dimension filters combine with AND over activity-derived figures. Reuse displayed stand-ins for missing values: Unknown, (direct), Untagged and (none). Inventory and receipt/rejection health counts have their own scope; do not assume every statistic applies the activity filters.
- Returns totals, previous-period comparison, series, rankings, journey, realtime, acquisition, content, apps, audience, event mix, paths, recent sessions and source health. Null percentage changes can represent an unavailable previous denominator.
- Rankings and recent sessions are bounded views, not full exports: top events 20, content pages 15, paths 16, many dimensions 12 and recent sessions 12 with a bounded activity sample. Separate queries do not provide an atomic snapshot.
- Queued receipts may be positive while processed event totals are zero. Empty reports and zero values are valid; they prove no traffic unless collection, time window and processing are independently verified.
Interpret the response
- Compare meta.days, meta.source, meta.actorId, filters and liveWindowMinutes with the approved request/context.
- Inspect dataHealth.queued/processed/rejected, sourceHealth and totals separately. Use repeated reads only to observe processing, not to assume immediate consistency.
- Interpret comparison percentages, nullable values and bounded ranking limits; do not sum dimension rankings as an exhaustive user count.
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.analytics.overview --data @payload.json --json
topolo actions plan app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions call app_topolo_insights.analytics.overview --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.analytics.overview",
"input": {}
}
}
Captured raw Worker result
{
"data": {
"totals": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0,
"liveVisitors": 0,
"sources": 0,
"eventDefinitions": 0,
"rejected": 0
},
"comparison": {
"previous": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0
},
"changes": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRatePoints": 0
}
},
"series": [],
"topEvents": [],
"events": [],
"dataHealth": {
"queued": 0,
"processed": 0,
"rejected": 0
},
"journey": [
{
"name": "page.viewed",
"label": "Page viewed",
"events": 0
},
{
"name": "cta.clicked",
"label": "CTA clicked",
"events": 0
},
{
"name": "checkout.started",
"label": "Checkout started",
"events": 0
},
{
"name": "checkout.completed",
"label": "Checkout completed",
"events": 0
}
],
"realtime": {
"activeVisitors": 0,
"activeSessions": 0,
"pages": []
},
"acquisition": {
"channels": [],
"campaigns": [],
"sources": [],
"mediums": [],
"referrers": []
},
"content": {
"pages": [],
"landingPages": [],
"exitPages": []
},
"apps": [],
"audience": {
"devices": [],
"countries": [],
"browsers": [],
"operatingSystems": [],
"screenClasses": []
},
"paths": [],
"recentSessions": [],
"sourceHealth": []
},
"meta": {
"days": 30,
"source": null,
"actorId": "usr_insights_fixture",
"liveWindowMinutes": 5,
"filters": {}
}
}
HTTP 200. Compare meta.days, meta.source, meta.actorId, filters and liveWindowMinutes with the approved request/context. Inspect dataHealth.queued/processed/rejected, sourceHealth and totals separately. Use repeated reads only to observe processing, not to assume immediate consistency. Interpret comparison percentages, nullable values and bounded ranking limits; do not sum dimension rankings as an exhaustive user count.
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:
{
"days": 7,
"source": "marketing-site"
}
CLI:
topolo actions validate app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions plan app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions call app_topolo_insights.analytics.overview --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.analytics.overview",
"input": {
"days": 7,
"source": "marketing-site"
}
}
}
Captured raw Worker result
{
"data": {
"totals": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0,
"liveVisitors": 0,
"sources": 1,
"eventDefinitions": 3,
"rejected": 5
},
"comparison": {
"previous": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0
},
"changes": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRatePoints": 0
}
},
"series": [],
"topEvents": [],
"events": [],
"dataHealth": {
"queued": 1,
"processed": 0,
"rejected": 5
},
"journey": [
{
"name": "page.viewed",
"label": "Page viewed",
"events": 0
},
{
"name": "cta.clicked",
"label": "CTA clicked",
"events": 0
},
{
"name": "checkout.started",
"label": "Checkout started",
"events": 0
},
{
"name": "checkout.completed",
"label": "Checkout completed",
"events": 0
}
],
"realtime": {
"activeVisitors": 0,
"activeSessions": 0,
"pages": []
},
"acquisition": {
"channels": [],
"campaigns": [],
"sources": [],
"mediums": [],
"referrers": []
},
"content": {
"pages": [],
"landingPages": [],
"exitPages": []
},
"apps": [],
"audience": {
"devices": [],
"countries": [],
"browsers": [],
"operatingSystems": [],
"screenClasses": []
},
"paths": [],
"recentSessions": [],
"sourceHealth": [
{
"sourceKey": "marketing-site",
"name": "Marketing site",
"status": "active",
"processed": 0,
"queued": 1,
"rejected": 5,
"lastSeenAt": "2026-10-04T08:52:48.570Z"
}
]
},
"meta": {
"days": 7,
"source": "marketing-site",
"actorId": "usr_insights_fixture",
"liveWindowMinutes": 5,
"filters": {}
}
}
HTTP 200. Compare meta.days, meta.source, meta.actorId, filters and liveWindowMinutes with the approved request/context. Inspect dataHealth.queued/processed/rejected, sourceHealth and totals separately. Use repeated reads only to observe processing, not to assume immediate consistency. Interpret comparison percentages, nullable values and bounded ranking limits; do not sum dimension rankings as an exhaustive user count.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
workflow · 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_workflow. Fixture handles authorize no live request.
Input · payload.json:
{
"days": 7,
"source": "marketing-site"
}
CLI:
topolo actions validate app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions plan app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions call app_topolo_insights.analytics.overview --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.analytics.overview",
"input": {
"days": 7,
"source": "marketing-site"
}
}
}
Captured raw Worker result
{
"data": {
"totals": {
"events": 1,
"visitors": 1,
"sessions": 1,
"pageViews": 1,
"bounceRate": 100,
"liveVisitors": 1,
"sources": 1,
"eventDefinitions": 3,
"rejected": 5
},
"comparison": {
"previous": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0
},
"changes": {
"events": null,
"visitors": null,
"sessions": null,
"pageViews": null,
"bounceRatePoints": 100
}
},
"series": [
{
"bucket": "2026-10-04",
"events": 1,
"visitors": 1,
"sessions": 1,
"pageViews": 1
}
],
"topEvents": [
{
"name": "page.viewed",
"events": 1
}
],
"events": [
{
"name": "page.viewed",
"events": 1,
"visitors": 1,
"sessions": 1,
"share": 100
}
],
"dataHealth": {
"queued": 0,
"processed": 1,
"rejected": 5
},
"journey": [
{
"name": "page.viewed",
"label": "Page viewed",
"events": 1
},
{
"name": "cta.clicked",
"label": "CTA clicked",
"events": 0
},
{
"name": "checkout.started",
"label": "Checkout started",
"events": 0
},
{
"name": "checkout.completed",
"label": "Checkout completed",
"events": 0
}
],
"realtime": {
"activeVisitors": 1,
"activeSessions": 1,
"pages": []
},
"acquisition": {
"channels": [
{
"name": "Direct",
"visitors": 1,
"sessions": 1
}
],
"campaigns": [
{
"name": "Untagged",
"visitors": 1,
"sessions": 1
}
],
"sources": [
{
"name": "(direct)",
"visitors": 1,
"sessions": 1
}
],
"mediums": [
{
"name": "(none)",
"visitors": 1,
"sessions": 1
}
],
"referrers": [
{
"name": "(direct)",
"visitors": 1,
"sessions": 1
}
]
},
"content": {
"pages": [],
"landingPages": [],
"exitPages": []
},
"apps": [
{
"name": "app_example",
"visitors": 1,
"sessions": 1
}
],
"audience": {
"devices": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"countries": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"browsers": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"operatingSystems": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"screenClasses": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
]
},
"paths": [],
"recentSessions": [
{
"id": "session_fixture_001",
"visitorId": "ture_001",
"startedAt": "2026-10-04T08:52:48.558Z",
"lastSeenAt": "2026-10-04T08:52:48.558Z",
"durationSeconds": 0,
"eventCount": 1,
"pageViews": 1,
"entryPath": null,
"exitPath": null,
"device": "Unknown",
"country": "Unknown",
"browser": "Unknown",
"operatingSystem": "Unknown",
"paths": []
}
],
"sourceHealth": [
{
"sourceKey": "marketing-site",
"name": "Marketing site",
"status": "active",
"processed": 1,
"queued": 0,
"rejected": 5,
"lastSeenAt": "2026-10-04T08:52:48.767Z"
}
]
},
"meta": {
"days": 7,
"source": "marketing-site",
"actorId": "usr_insights_fixture",
"liveWindowMinutes": 5,
"filters": {}
}
}
HTTP 200. Compare meta.days, meta.source, meta.actorId, filters and liveWindowMinutes with the approved request/context. Inspect dataHealth.queued/processed/rejected, sourceHealth and totals separately. Use repeated reads only to observe processing, not to assume immediate consistency. Interpret comparison percentages, nullable values and bounded ranking limits; do not sum dimension rankings as an exhaustive user count.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
workflow · success 4 · 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:
{
"country": "GB",
"app": "app_example",
"page": "/pricing"
}
CLI:
topolo actions validate app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions plan app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions call app_topolo_insights.analytics.overview --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.analytics.overview",
"input": {
"country": "GB",
"app": "app_example",
"page": "/pricing"
}
}
}
Captured raw Worker result
{
"data": {
"totals": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0,
"liveVisitors": 0,
"sources": 1,
"eventDefinitions": 3,
"rejected": 6
},
"comparison": {
"previous": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0
},
"changes": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRatePoints": 0
}
},
"series": [],
"topEvents": [],
"events": [],
"dataHealth": {
"queued": 0,
"processed": 1,
"rejected": 6
},
"journey": [
{
"name": "page.viewed",
"label": "Page viewed",
"events": 0
},
{
"name": "cta.clicked",
"label": "CTA clicked",
"events": 0
},
{
"name": "checkout.started",
"label": "Checkout started",
"events": 0
},
{
"name": "checkout.completed",
"label": "Checkout completed",
"events": 0
}
],
"realtime": {
"activeVisitors": 0,
"activeSessions": 0,
"pages": []
},
"acquisition": {
"channels": [],
"campaigns": [],
"sources": [],
"mediums": [],
"referrers": []
},
"content": {
"pages": [],
"landingPages": [],
"exitPages": []
},
"apps": [],
"audience": {
"devices": [],
"countries": [],
"browsers": [],
"operatingSystems": [],
"screenClasses": []
},
"paths": [],
"recentSessions": [],
"sourceHealth": [
{
"sourceKey": "marketing-site",
"name": "Marketing site",
"status": "active",
"processed": 1,
"queued": 0,
"rejected": 5,
"lastSeenAt": "2026-10-04T08:52:48.767Z"
}
]
},
"meta": {
"days": 30,
"source": null,
"actorId": "usr_insights_fixture",
"liveWindowMinutes": 5,
"filters": {
"page": "/pricing",
"app": "app_example",
"country": "GB"
}
}
}
HTTP 200. Compare meta.days, meta.source, meta.actorId, filters and liveWindowMinutes with the approved request/context. Inspect dataHealth.queued/processed/rejected, sourceHealth and totals separately. Use repeated reads only to observe processing, not to assume immediate consistency. Interpret comparison percentages, nullable values and bounded ranking limits; do not sum dimension rankings as an exhaustive user count.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
workflow · refusal 5 · HTTP 404
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:
{
"source": "missing-site"
}
CLI:
topolo actions validate app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions plan app_topolo_insights.analytics.overview --data @payload.json --json
Captured raw Worker result
{
"error": "source_not_found"
}
HTTP 404. Discover the active source id/key in the selected workspace; organization ids and display names are not source handles.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
transferred · success 6 · 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_target. Fixture handles authorize no live request.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions plan app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions call app_topolo_insights.analytics.overview --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.analytics.overview",
"input": {}
}
}
Captured raw Worker result
{
"data": {
"totals": {
"events": 2,
"visitors": 1,
"sessions": 1,
"pageViews": 2,
"bounceRate": 0,
"liveVisitors": 1,
"sources": 1,
"eventDefinitions": 0,
"rejected": 5
},
"comparison": {
"previous": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0
},
"changes": {
"events": null,
"visitors": null,
"sessions": null,
"pageViews": null,
"bounceRatePoints": 0
}
},
"series": [
{
"bucket": "2026-10-04",
"events": 2,
"visitors": 1,
"sessions": 1,
"pageViews": 2
}
],
"topEvents": [
{
"name": "page.viewed",
"events": 2
}
],
"events": [
{
"name": "page.viewed",
"events": 2,
"visitors": 1,
"sessions": 1,
"share": 100
}
],
"dataHealth": {
"queued": 0,
"processed": 2,
"rejected": 5
},
"journey": [
{
"name": "page.viewed",
"label": "Page viewed",
"events": 2
},
{
"name": "cta.clicked",
"label": "CTA clicked",
"events": 0
},
{
"name": "checkout.started",
"label": "Checkout started",
"events": 0
},
{
"name": "checkout.completed",
"label": "Checkout completed",
"events": 0
}
],
"realtime": {
"activeVisitors": 1,
"activeSessions": 1,
"pages": []
},
"acquisition": {
"channels": [
{
"name": "Direct",
"visitors": 1,
"sessions": 1
}
],
"campaigns": [
{
"name": "Untagged",
"visitors": 1,
"sessions": 1
}
],
"sources": [
{
"name": "(direct)",
"visitors": 1,
"sessions": 1
}
],
"mediums": [
{
"name": "(none)",
"visitors": 1,
"sessions": 1
}
],
"referrers": [
{
"name": "(direct)",
"visitors": 1,
"sessions": 1
}
]
},
"content": {
"pages": [],
"landingPages": [],
"exitPages": []
},
"apps": [
{
"name": "app_example",
"visitors": 1,
"sessions": 1
}
],
"audience": {
"devices": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"countries": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"browsers": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"operatingSystems": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"screenClasses": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
]
},
"paths": [],
"recentSessions": [
{
"id": "session_fixture_001",
"visitorId": "ture_001",
"startedAt": "2026-10-04T08:52:48.558Z",
"lastSeenAt": "2026-10-04T08:52:48.558Z",
"durationSeconds": 0,
"eventCount": 2,
"pageViews": 2,
"entryPath": null,
"exitPath": null,
"device": "Unknown",
"country": "Unknown",
"browser": "Unknown",
"operatingSystem": "Unknown",
"paths": []
}
],
"sourceHealth": [
{
"sourceKey": "marketing-site",
"name": "Marketing site",
"status": "active",
"processed": 2,
"queued": 0,
"rejected": 5,
"lastSeenAt": "2026-10-04T08:52:48.976Z"
}
]
},
"meta": {
"days": 30,
"source": null,
"actorId": "usr_insights_fixture",
"liveWindowMinutes": 5,
"filters": {}
}
}
HTTP 200. Compare meta.days, meta.source, meta.actorId, filters and liveWindowMinutes with the approved request/context. Inspect dataHealth.queued/processed/rejected, sourceHealth and totals separately. Use repeated reads only to observe processing, not to assume immediate consistency. Interpret comparison percentages, nullable values and bounded ranking limits; do not sum dimension rankings as an exhaustive user count.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
merge · success 7 · 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.analytics.overview --data @payload.json --json
topolo actions plan app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions call app_topolo_insights.analytics.overview --data @payload.json --detail --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_insights.analytics.overview",
"input": {}
}
}
Captured raw Worker result
{
"data": {
"totals": {
"events": 2,
"visitors": 1,
"sessions": 1,
"pageViews": 2,
"bounceRate": 0,
"liveVisitors": 1,
"sources": 1,
"eventDefinitions": 0,
"rejected": 5
},
"comparison": {
"previous": {
"events": 0,
"visitors": 0,
"sessions": 0,
"pageViews": 0,
"bounceRate": 0
},
"changes": {
"events": null,
"visitors": null,
"sessions": null,
"pageViews": null,
"bounceRatePoints": 0
}
},
"series": [
{
"bucket": "2026-10-04",
"events": 2,
"visitors": 1,
"sessions": 1,
"pageViews": 2
}
],
"topEvents": [
{
"name": "page.viewed",
"events": 2
}
],
"events": [
{
"name": "page.viewed",
"events": 2,
"visitors": 1,
"sessions": 1,
"share": 100
}
],
"dataHealth": {
"queued": 0,
"processed": 2,
"rejected": 5
},
"journey": [
{
"name": "page.viewed",
"label": "Page viewed",
"events": 2
},
{
"name": "cta.clicked",
"label": "CTA clicked",
"events": 0
},
{
"name": "checkout.started",
"label": "Checkout started",
"events": 0
},
{
"name": "checkout.completed",
"label": "Checkout completed",
"events": 0
}
],
"realtime": {
"activeVisitors": 1,
"activeSessions": 1,
"pages": []
},
"acquisition": {
"channels": [
{
"name": "Direct",
"visitors": 1,
"sessions": 1
}
],
"campaigns": [
{
"name": "Untagged",
"visitors": 1,
"sessions": 1
}
],
"sources": [
{
"name": "(direct)",
"visitors": 1,
"sessions": 1
}
],
"mediums": [
{
"name": "(none)",
"visitors": 1,
"sessions": 1
}
],
"referrers": [
{
"name": "(direct)",
"visitors": 1,
"sessions": 1
}
]
},
"content": {
"pages": [],
"landingPages": [],
"exitPages": []
},
"apps": [
{
"name": "app_example",
"visitors": 1,
"sessions": 1
}
],
"audience": {
"devices": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"countries": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"browsers": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"operatingSystems": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
],
"screenClasses": [
{
"name": "Unknown",
"visitors": 1,
"sessions": 1
}
]
},
"paths": [],
"recentSessions": [
{
"id": "session_fixture_001",
"visitorId": "ture_001",
"startedAt": "2026-10-04T08:52:48.558Z",
"lastSeenAt": "2026-10-04T08:52:48.558Z",
"durationSeconds": 0,
"eventCount": 2,
"pageViews": 2,
"entryPath": null,
"exitPath": null,
"device": "Unknown",
"country": "Unknown",
"browser": "Unknown",
"operatingSystem": "Unknown",
"paths": []
}
],
"sourceHealth": [
{
"sourceKey": "target-property",
"name": "Target property",
"status": "active",
"processed": 2,
"queued": 0,
"rejected": 0,
"lastSeenAt": "2026-10-04T08:52:48.976Z"
}
]
},
"meta": {
"days": 30,
"source": null,
"actorId": "usr_insights_fixture",
"liveWindowMinutes": 5,
"filters": {}
}
}
HTTP 200. Compare meta.days, meta.source, meta.actorId, filters and liveWindowMinutes with the approved request/context. Inspect dataHealth.queued/processed/rejected, sourceHealth and totals separately. Use repeated reads only to observe processing, not to assume immediate consistency. Interpret comparison percentages, nullable values and bounded ranking limits; do not sum dimension rankings as an exhaustive user count.
CLI/MCP adds its transport envelope; CLI --detail retains the full action result.
permission-refusals · refusal 8 · 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:
{
"days": 30,
"country": "GB"
}
CLI:
topolo actions validate app_topolo_insights.analytics.overview --data @payload.json --json
topolo actions plan app_topolo_insights.analytics.overview --data @payload.json --json
Captured raw Worker result
{
"success": false,
"error": {
"code": "action_permission_required",
"message": "Action \"analytics.overview\" requires permission \"workspace:read\".",
"action": "analytics.overview"
}
}
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
- Compare meta.days, meta.source, meta.actorId, filters and liveWindowMinutes with the approved request/context.
- Inspect dataHealth.queued/processed/rejected, sourceHealth and totals separately. Use repeated reads only to observe processing, not to assume immediate consistency.
- Interpret comparison percentages, nullable values and bounded ranking limits; do not sum dimension rankings as an exhaustive user count.
Errors and recovery
source_not_found(HTTP 404): Discover the active source id/key in the selected workspace; organization ids and display names are not source handles.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.sources.list: List the selected workspace’s registered analytics sources.
- app_topolo_insights.event_definitions.list: Read the selected workspace’s governed event name/version/purpose declarations.
- app_topolo_insights.dashboards.list: Read saved dashboard configuration and ordered widgets in the selected workspace.
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.