Activity API and MCP

Activity uses the signed-in account's existing file permissions. REST accepts the usual authenticated session or API token; MCP uses its authenticated user. All responses are private and must not be publicly cached. The activity guide defines counting and plan retention.

MCP tools

root is a shared-space slug, or ~ for the caller's My documents. owner is an email address. Sort is views, downloads, edits or recent. Rankings and events return at most 100 rows. Days are clamped to the current plan's aggregate window. Summary access requires edit permission; a specified inaccessible file returns not found.

REST

• GET /api/activity/summary takes optional doc_id, root, folder, owner, plus days=30, sort=views, limit=50, offset=0.
• GET /api/activity/events accepts the same scope filters plus before_id, after_id, limit=50, reveal_ip=false.
• GET /api/activity/status accepts the scope filters and optional cursor.

REST validates days from 1 to 1,095 and page size from 1 to 100. A summary returns views, downloads, known_views, anonymous_views, edits, event counts, channel counts, audience access_modes, a zero-filled daily series, ranked files, total_files, retention, details_allowed, cursor and updated_at.

Channels are audience, internal, bot and automation. The channels counts cover opens and downloads; the events map covers all recorded event types. Form events (form.started, form.saved, form.completed) belong to the response database. automation.read currently records MCP get_file reads; other read tools do not create page views.

Poll without rereading history

1. Call activity_status for a file or folder. Save the returned cursor.
2. Wait at least poll_after seconds (currently 15), then pass that cursor with the same scope.
3. When changed is true, fetch the summary or retained events you need and save the new cursor.

The cursor checks accessible files and their revision counters, not the full event history. It also changes when accessible files, management rights, the plan or the UTC day changes. Permissions are checked again on every call. It does not run a background task for the agent; the client must schedule its own checks.

For event catch-up, start with after_id=0 and consume rows in ascending ID order, saving next_after_id. Repeat until there are no new rows. Use before_id and next_before_id for browsing older events instead. Do not combine the two directions. A cursor is not an indefinite replay guarantee: expired detail cannot be retrieved. Use daily aggregates for longer trends and the database change feed for response-level synchronization.

IP addresses are masked unless reveal_ip=true, and that option never widens permissions. Free returns daily totals with an empty detail timeline. Plan upgrades do not reconstruct earlier identities or IPs.