Summarize Feed impressions

Outcome

Group impressions by media and event type in the granted workspace, using inclusive millisecond bounds and a SQL LIKE media pattern. The request can initialize the local workspace mirror.

Before you start

• Verify the authenticated identity, exact environment and pinned approved organization context before preparing an action.
• Development stores content without encryption and uses scoped SHA-256 identifier hashes. Staging and production require envelope encryption and a provisioned application root; missing custody does not permit plaintext.
• The published application permission is analytics:read. Discover a granted Feed workspace and bind that exact resource. Supplied identifiers and query selectors do not grant access.
• Authorize the documented mirror, security, external-fetch, reporting, privacy or archival effects before CLI --confirm or MCP confirm:true. A GET request can initialize a local mirror.

Discover the target

topolo whoami --json
topolo actions get app_topolo_feed.analytics.summary.get --detail --json
topolo resources topolo-feed --json
topolo workspaces list topolo-feed --json

• Select the exact granted workspace id as FEED_WORKSPACE_ID. Fixture ids authorize no live operation.

Request

GET /api/analytics/summary

Save action input as payload.json. Inspect the plan for the exact path, query and body. Set FEED_WORKSPACE_ID from granted resource discovery.

Inspect and test this action in the signed action console, then perform the verification below.

Input fields

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "minLength": 1,
      "description": "Canonical Feed workspace id. Resolve it through credential-scoped grants; it does not grant access. For archival it is also the path id and must match the resolved resource."
    },
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "description": "Alternative workspace selector accepted by the published input. Prefer one explicit granted workspace resource; do not send conflicting selectors."
    },
    "start_time": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Inclusive window start in Unix milliseconds; defaults to 0. Numeric strings are coerced by action validation."
    },
    "end_time": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Inclusive window end in Unix milliseconds; defaults to server current time. Numeric strings are coerced by action validation."
    },
    "ad_id_pattern": {
      "type": "string",
      "description": "SQL LIKE media identifier pattern, default %. % and _ retain SQL wildcard meaning; this is not a regular expression."
    }
  },
  "additionalProperties": false
}

Effects

• Resolves the workspace through platform grants and can insert its identity-only local mirror before the route permission check. GET is therefore a mutation for action planning; it does not create a canonical workspace or change its name.
• Returns count, summed and average duration for each media/event group, distinct device fingerprints and the resolved time bounds. Default start is 0, end is the server current time and pattern is %.

Interpret the response

This action can return no new resource identifier. Follow the specific response verification and do not invent a target id.

Confirm time_range and the intended granted workspace. The response is an unpaginated aggregate ordered by media and event type; it contains no individual event records.

The success schema below was checked against captured handler responses. Polymorphic configuration and protected device assignment fields vary; exact envelope and SQL row fields are source-reviewed. Error examples retain their actual refusal shapes.

Success schema:

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "media_id": {
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "count": {
            "type": "number"
          },
          "total_duration": {
            "type": "number"
          },
          "avg_duration": {
            "type": "number"
          }
        },
        "required": [
          "media_id",
          "event_type",
          "count",
          "total_duration",
          "avg_duration"
        ],
        "additionalProperties": false
      }
    },
    "unique_devices": {
      "type": "number"
    },
    "time_range": {
      "type": "object",
      "properties": {
        "start_time": {
          "type": "number"
        },
        "end_time": {
          "type": "number"
        }
      },
      "required": [
        "start_time",
        "end_time"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "summary",
    "unique_devices",
    "time_range"
  ],
  "additionalProperties": false
}

Worked examples

Actual Feed Worker response using synthetic Auth, workspace grants, in-memory D1/KV and simulated source/notification transport. No live provider, encryption audit, device enrollment or external delivery is established. Credentials are excluded or explicitly redacted. SQL result shapes are also reviewed against migrations and handlers; empty captures do not exercise every populated export store. Live publication and read-back are separate environment evidence. Refused examples demonstrate boundaries and must not be executed as successful workflows.

Successful request

Actual Feed Worker response using synthetic Auth, workspace grants, in-memory D1/KV and simulated source/notification transport. No live provider, encryption audit, device enrollment or external delivery is established. Credentials are excluded or explicitly redacted. Captured scenario: impression summary is isolated per workspace.

Input · payload.json:

{
  "start_time": 0,
  "end_time": 100
}

CLI:

topolo actions validate app_topolo_feed.analytics.summary.get --data @payload.json --json
topolo actions plan app_topolo_feed.analytics.summary.get --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_feed.analytics.summary.get --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_feed.analytics.summary.get",
    "input": {
      "start_time": 0,
      "end_time": 100
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "summary": [
    {
      "media_id": "media_a",
      "event_type": "impression_start",
      "count": 1,
      "total_duration": 10,
      "avg_duration": 10
    }
  ],
  "unique_devices": 1,
  "time_range": {
    "start_time": 0,
    "end_time": 100
  }
}

HTTP 200. Confirm time_range and the intended granted workspace. The response is an unpaginated aggregate ordered by media and event type; it contains no individual event records.

Another supported request

Actual Feed Worker response using synthetic Auth, workspace grants, in-memory D1/KV and simulated source/notification transport. No live provider, encryption audit, device enrollment or external delivery is established. Credentials are excluded or explicitly redacted. Captured scenario: impression summary is isolated per workspace.

Input · payload.json:

{
  "start_time": 0,
  "end_time": 100
}

CLI:

topolo actions validate app_topolo_feed.analytics.summary.get --data @payload.json --json
topolo actions plan app_topolo_feed.analytics.summary.get --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_feed.analytics.summary.get --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_feed.analytics.summary.get",
    "input": {
      "start_time": 0,
      "end_time": 100
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "summary": [
    {
      "media_id": "media_b",
      "event_type": "impression_start",
      "count": 1,
      "total_duration": 10,
      "avg_duration": 10
    }
  ],
  "unique_devices": 1,
  "time_range": {
    "start_time": 0,
    "end_time": 100
  }
}

HTTP 200. Confirm time_range and the intended granted workspace. The response is an unpaginated aggregate ordered by media and event type; it contains no individual event records.

Verify the result

• Confirm time_range and the intended granted workspace. The response is an unpaginated aggregate ordered by media and event type; it contains no individual event records.

Errors and recovery

• forbidden (HTTP 403): Use the published permission in the approved credential scope. Do not switch contexts to bypass a denial.

Auth, action-input validation and platform resource resolution can refuse a request before its handler. Retain the exact error, request id and context; requesting another context is not a legitimate way to bypass a refusal.

Recovery boundary

No aggregate rows are changed. The identity-only mirror can remain after the request; do not archive a workspace to undo an analytics read.

Related actions

• Get Feed engagement metrics: Calculate workspace completion, touch interaction and duration metrics by media for inclusive millisecond bounds and a SQL LIKE pattern. Empty results are valid; the request can initialize the local mirror.

Evidence

Actual Feed Worker response using synthetic Auth, workspace grants, in-memory D1/KV and simulated source/notification transport. No live provider, encryption audit, device enrollment or external delivery is established. Credentials are excluded or explicitly redacted. SQL result shapes are also reviewed against migrations and handlers; empty captures do not exercise every populated export store. Live publication and read-back are separate environment evidence. Capture digests and test scenarios are retained in the source fixture records.