Engagement Report

skill

Pull engagement metrics via API, compute results, and share a report file with the team.

Download .md

Engagement Report

Pull social media engagement metrics from a connected platform API, compute period-over-period results, and share a report file with the team.

When to use

  • A teammate asks for likes/comments/shares/reach numbers for a campaign or date range.
  • A recurring cadence (weekly/monthly) requires a fresh engagement summary.
  • Leadership needs a quick read on which posts or channels are over/underperforming.
  • Someone requests a comparison of engagement across accounts or time windows.

Tools

  • http-get: retrieve engagement metrics (likes, comments, shares, reach, impressions) from the social platform's REST API.
  • shell-execute: run a small script to aggregate, dedupe, and compute period-over-period metric math on the pulled data.
  • write-file: save the computed report as a file (e.g. markdown or CSV) for the team.
  • send-message: notify the requesting human or another agent that the report is ready, and escalate any blockers.

Playbook

  1. Confirm the request scope: platform(s), account(s), date range, and which metrics matter (likes, comments, shares, reach, impressions).
  2. Call the social platform REST API with http-get (e.g. GET https://graph.facebook.com/v19.0/{page-id}/insights). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. If the call returns 401/403 or no Integration row exists, stop and message a human via send-message asking them to create the Integration, naming the service and required scopes.
  3. If multiple accounts or date ranges are needed, repeat step 2 with http-get for each page/endpoint, paginating until all results for the window are collected.
  4. Use shell-execute to parse the raw JSON responses, normalize field names across accounts, and merge into a single dataset.
  5. Use shell-execute to compute totals, averages, and period-over-period deltas (e.g. this week vs last week) for each metric.
  6. Use shell-execute to identify top and bottom performing posts by engagement rate, flagging any outliers worth calling out.
  7. Draft the report body (summary, key numbers, top/bottom posts, notable trends) and save it with write-file to a clearly named report file.
  8. If any requested change to the underlying data (e.g. correcting a post's metadata via PATCH/PUT/DELETE) is needed, this is NOT possible with the declared tools — compile the change list into the report file via write-file and hand off to a human via send-message rather than attempting it.
  9. Notify the requester via send-message that the report file is ready, including its location and a one-line summary of the headline finding.

Failure modes

  • API call returns 401/403 -> missing Integration; stop and escalate via send-message naming the service and required scopes.
  • Empty or near-empty result set -> verify the endpoint URL, account ID, and date-range parameters before re-querying.
  • Rate limit hit -> back off and retry later; note the limit and timing in memory so future runs pace requests accordingly.
  • Platform page/API structure changed and results look malformed -> fall back to browser-search to confirm current endpoint documentation before retrying.

Done when

  • A report file exists (via write-file) containing computed engagement totals, deltas, and top/bottom performers for the requested scope.
  • The requester or team has been notified via send-message with the report location and headline summary.
  • Any data-correction needs beyond read access are documented in the report and explicitly routed to a human, not silently skipped.