Inspect Socialize dashboard metrics in the original authorized scope.
Before you start
- Verify production, original organization and credential, published dashboard:read permission, and canonical workspace grants. Bind an explicitly selected workspace separately from the empty action input. An app/widget id is not a workspace grant.
- Examples are source-derived synthetic UNRUN. Exact English source strings are used under an explicit packaged-English assumption; no widget/business/private/provider action or application import/test was performed. The declared source association does not prove that source is serving.
Request
GET /api/widget
Action: app_topolo_socialize.widget.get. Input is exactly {}; selection stays in separately bound resource context.
Interpret the widget
The input is exactly {}. With no named resource, aggregate only canonical accessible workspaces filtered by API-key bindings and required read grant. With a named workspace, intersect that exact id with authorized ids; no fallback to all workspaces. Named but inaccessible/unresolved selection can produce an empty widget at this layer rather than proving that the workspace does not exist. Earlier auth middleware may refuse first.
listBrandWorkspaces synchronizes authorized local workspace mirrors before metric SQL reads. Therefore the complete request is not guaranteed to make zero database writes, despite the read declaration. No posting, campaign creation, model generation or provider delivery follows from this read.
Six metrics report current accessible-workspace count, all campaign rows, scheduled/draft/published stored post-status counts and active campaign status count. They are not unique people, deliveries, engagement, date-filtered trends or a provider reconciliation. Failed-at mapping used by the post-list route is not applied to this SQL status aggregation.
Five SQL-derived counts come from two concurrent queries; the workspace count comes from the authorized workspace ids. These are not a transactional snapshot. No accessible selected workspace produces state.empty with metrics:[], while static metric definitions remain present. An accessible workspace with no rows instead produces ready and zero values.
Returned widget is socialize.content-operations version1.0.0 in contract3.0.0. SDK0.23.22 adds appId/serviceName/lastUpdated and validates its carrier. generatedAt/observedAt show response construction, not the last external provider synchronization.
A named accessible workspace offers create-campaign control and actions visualization. Its input:{} is a template, not a complete authorized campaigns.create request. Discover and supply the actual schema, confirmation and grants separately; control visibility is not authorization. Aggregate and empty widgets omit this control.
Refresh metadata recommends60seconds and20second timeout, maxAge300/staleWhileRevalidate300; these fields do not schedule a job. Handler success header is public,max-age=15, error no-store. Treat response as credential-scoped data and do not assume safe shared caching or cache isolation merely from this header.
Worked examples
No accessible workspace in the verified organization
Complete source-derived synthetic UNRUN HTTP200, assuming original authenticated org_docs_fixture, no accessible workspace, default English source copy correctly packaged and SDK0.23.22 carrier. No runtime availability or translation-release attestation is implied.
{}
Illustrative response:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_socialize",
"serviceName": "Socialize",
"generatedAt": "2026-10-21T12:00:00.000Z",
"widgets": [
{
"id": "socialize.content-operations",
"version": "1.0.0",
"type": "stats",
"presentation": {
"title": "Social content operations",
"description": "Socialize is reporting current brand, campaign, post, and publishing counts.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "organization",
"resourceId": "org_docs_fixture",
"requiredPermissions": [
"dashboard:read"
]
},
"state": {
"status": "empty",
"observedAt": "2026-10-21T12:00:00.000Z",
"lastSuccessfulAt": "2026-10-21T12:00:00.000Z",
"message": "No accessible brands are available in this organization."
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 20,
"maxAgeSeconds": 300,
"staleWhileRevalidateSeconds": 300
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [
{
"id": "campaigns",
"label": "View campaigns",
"href": "/campaigns"
},
{
"id": "calendar",
"label": "Open calendar",
"href": "/calendar"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "socialize.api.widget.contentOperationsTitle",
"descriptionKey": "socialize.api.widget.contentOperationsDescription",
"title": "Social content operations",
"description": "Brand, campaign, post, and publishing activity across your connected social accounts."
},
"accessibility": {
"label": "Social content operations metrics and actions"
},
"contribution": {
"summary": "Campaign and publishing throughput for the selected brand workspace scope.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "optional",
"resourceType": "workspace",
"label": "Brand workspace",
"supportsMultiple": true
},
"metricDefinitions": [
{
"key": "brands",
"label": "Brands",
"description": "Accessible brand workspaces included in this scope.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "campaigns",
"label": "Campaigns",
"description": "Campaigns created in the selected brand workspace scope.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "scheduled_posts",
"label": "Scheduled",
"description": "Posts currently scheduled for publication.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "draft_posts",
"label": "Drafts",
"description": "Posts currently in draft.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "active_campaigns",
"label": "Active campaigns",
"description": "Campaigns currently active.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "published_posts",
"label": "Published posts",
"description": "Posts published in the selected brand workspace scope.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Brand workspace scope",
"description": "The selected brand workspace or accessible workspace set.",
"valueType": "string"
},
{
"key": "campaign_status",
"label": "Campaign status",
"description": "The current campaign lifecycle status.",
"valueType": "string"
},
{
"key": "post_status",
"label": "Post status",
"description": "The current publishing lifecycle status.",
"valueType": "string"
}
],
"lifecycleStages": [
{
"key": "campaign_draft",
"label": "Campaign draft",
"order": 0,
"terminal": false
},
{
"key": "campaign_scheduled",
"label": "Campaign scheduled",
"order": 1,
"terminal": false
},
{
"key": "campaign_active",
"label": "Campaign active",
"order": 2,
"terminal": false
},
{
"key": "campaign_completed",
"label": "Campaign completed",
"order": 3,
"terminal": true
},
{
"key": "post_draft",
"label": "Post draft",
"order": 4,
"terminal": false
},
{
"key": "post_scheduled",
"label": "Post scheduled",
"order": 5,
"terminal": false
},
{
"key": "post_published",
"label": "Post published",
"order": 6,
"terminal": true
}
],
"events": [
{
"key": "campaign_created",
"label": "Campaign created",
"description": "A campaign was created in a brand workspace."
},
{
"key": "campaign_status_changed",
"label": "Campaign status changed",
"description": "A campaign moved to another lifecycle stage."
},
{
"key": "post_status_changed",
"label": "Post status changed",
"description": "A post moved to another publishing stage."
}
],
"datasets": [
{
"id": "social_content_operations",
"label": "Social content operations",
"description": "Campaign and post inventory in the selected brand workspace scope.",
"grain": "One aggregate row per selected brand workspace scope.",
"metricKeys": [
"brands",
"campaigns",
"scheduled_posts",
"draft_posts",
"active_campaigns",
"published_posts"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"campaign_status",
"post_status"
],
"eventKeys": [
"campaign_created",
"campaign_status_changed",
"post_status_changed"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "bar"
},
"metrics": [],
"appId": "app_topolo_socialize",
"serviceName": "Socialize",
"lastUpdated": "2026-10-21T12:00:00.000Z"
}
]
}
Widget construction cannot obtain its dependencies
Complete synthetic UNRUN HTTP503 produced by the route catch. This is an error carrier, not a successful outputSchema witness; do not convert it into successful zero metrics.
{}
Illustrative response:
{
"success": false,
"contractVersion": "3.0.0",
"appId": "app_topolo_socialize",
"serviceName": "Socialize",
"generatedAt": "2026-10-21T12:00:00.000Z",
"widgets": [],
"error": {
"code": "socialize_widget_unavailable",
"message": "Socialize widget data is temporarily unavailable.",
"retryable": true
}
}
Verify and recover
Check success, contractVersion, returned appId and widget id; bind response interpretation to the original selected scope. Read state.status and metrics separately: static contribution definitions do not mean observations exist.
If scope is unexpected or missing, rediscover actual grants and selected resource instead of treating zero/empty as proof of global absence. SQL failure is unavailable, not zero. Generated timestamps do not prove delivery.
On refusal reauthenticate or obtain the exact published grant through supported procedures; never substitute another organization/workspace silently.
For socialize_widget_unavailable preserve request id and selected scope; dependency resolution, local mirror or database problems may be involved. Use a bounded read retry after the underlying condition changes; do not create posts/campaigns to repair a dashboard read. No rollback mutation is applicable to reading metrics.
Changelog
2026-10-21: qualified declared-source widget aggregation, empty-state and error carriers, scope and mirror effects. Examples remain synthetic UNRUN; no deployment or browser certification.