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.

Outcome

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.engagement.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/engagement

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

Field	Required	Type	Constraints
`workspaceId`	Optional	string	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.; {"minLength":1}
`workspace_id`	Optional	string	Alternative workspace selector accepted by the published input. Prefer one explicit granted workspace resource; do not send conflicting selectors.; {"minLength":1}
`start_time`	Optional	integer	Inclusive window start in Unix milliseconds; defaults to 0. Numeric strings are coerced by action validation.; {"minimum":0,"maximum":9007199254740991}
`end_time`	Optional	integer	Inclusive window end in Unix milliseconds; defaults to server current time. Numeric strings are coerced by action validation.; {"minimum":0,"maximum":9007199254740991}
`ad_id_pattern`	Optional	string	SQL LIKE media identifier pattern, default %. % and _ retain SQL wildcard meaning; this is not a regular expression.; {}

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.
Completion and interaction rates divide by starts, round to two decimals and return 0 for zero starts. Average duration uses positive-duration completes; maximum uses completes.

Interpret the response

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

Inspect engagement and time_range. An empty array discovers no media identifier and does not justify creating an anomaly or device.

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": {
    "engagement": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "media_id": {
            "type": "string"
          },
          "impression_starts": {
            "type": "number"
          },
          "impression_completes": {
            "type": "number"
          },
          "touch_interactions": {
            "type": "number"
          },
          "completion_rate": {
            "type": "number"
          },
          "interaction_rate": {
            "type": "number"
          },
          "avg_duration": {
            "type": "number"
          },
          "max_duration": {
            "type": "number"
          }
        },
        "required": [
          "media_id",
          "impression_starts",
          "impression_completes",
          "touch_interactions",
          "completion_rate",
          "interaction_rate",
          "avg_duration",
          "max_duration"
        ],
        "additionalProperties": false
      }
    },
    "time_range": {
      "type": "object",
      "properties": {
        "start_time": {
          "type": "number"
        },
        "end_time": {
          "type": "number"
        }
      },
      "required": [
        "start_time",
        "end_time"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "engagement",
    "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

Input · payload.json:

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

CLI:

topolo actions validate app_topolo_feed.analytics.engagement.get --data @payload.json --json
topolo actions plan app_topolo_feed.analytics.engagement.get --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_feed.analytics.engagement.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.engagement.get",
    "input": {
      "start_time": 0,
      "end_time": 10
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "engagement": [],
  "time_range": {
    "start_time": 0,
    "end_time": 10
  }
}

HTTP 200. Inspect engagement and time_range. An empty array discovers no media identifier and does not justify creating an anomaly or device.

Another supported request

Input · payload.json:

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

CLI:

topolo actions validate app_topolo_feed.analytics.engagement.get --data @payload.json --json
topolo actions plan app_topolo_feed.analytics.engagement.get --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_feed.analytics.engagement.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.engagement.get",
    "input": {
      "start_time": 0,
      "end_time": 10
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "engagement": [
    {
      "media_id": "media",
      "impression_starts": 1,
      "impression_completes": 0,
      "touch_interactions": 0,
      "completion_rate": 0,
      "interaction_rate": 0,
      "avg_duration": 0,
      "max_duration": 0
    }
  ],
  "time_range": {
    "start_time": 0,
    "end_time": 10
  }
}

HTTP 200. Inspect engagement and time_range. An empty array discovers no media identifier and does not justify creating an anomaly or device.

Verify the result

Inspect engagement and time_range. An empty array discovers no media identifier and does not justify creating an anomaly or device.

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 records are changed. Do not repeat merely to create a mirror or infer a device enrollment.

Summarize Feed impressions: 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.

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.

Get Feed engagement metrics

Outcome

Before you start

Discover the target

Request

Input fields

Effects

Interpret the response

Worked examples

Successful request

Another supported request

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence