Choose a workspace and a source
Insights uses Auth-owned organization and workspace identity. Discover a granted workspace independently of bootstrap. One active source is supported per workspace; source and website collector creation require admin access, whereas event definitions, ingestion and dashboard edits require read_write access plus their published permissions.
Register governed events before collection
Register the source and exact event name/version/purpose before ingestion. Analytics events require a decisionReference; its presence is not proof of an external consent decision. A website collection key is origin-restricted, returned once, and separate from the signed ingestion action. Cookieless and consent modes have different browser identity behavior.
Read acceptance and processing separately
Inspect accepted, duplicates and rejected arrays for every batch. HTTP 202 can include rejections; HTTP 200 can contain only duplicates or rejections. Queue acceptance does not prove processing, archives, analytics visibility or hosted delivery. Preserve event ids after uncertain calls and inspect dataHealth rather than changing ids to force another acceptance.
Interpret bounded analytics
Analytics supplies audience, acquisition, content, comparison, events, paths, recent sessions and source health. Time windows, source and dimension filters affect reported activity; inventory and health counts have their own scope. Rankings are bounded and separate queries are not an atomic snapshot or full data export. The widget summarizes saved assets, not event traffic.
Save dashboards and replace configuration deliberately
Save one to eight distinct widget kinds with a 7, 30 or 90 day window and nullable source key. Updates replace the entire editable configuration and assign new widget ids; deletion permanently removes configuration while analytics remains. Read the original editable fields before replacement, and do not send output-only ids or positions as inputs.
Review source transfer and merge boundaries
Transfer requires administration of both workspaces. Database movement leaves event definitions, dashboards, raw archive keys and pending queue envelopes outside the transfer. Merge combines into the surviving target source; the response retains the old source id. Re-discover the target and do not claim merged data can be separated by transferring back.
Understand organization inventory and erasure
Organization export is a counts-and-object-metadata inventory, not a row/object backup. Erasure is organization-wide within this environment even when a workspace is selected. Review exact ERASE confirmation, verify remaining counts, and disclose the excluded Auth identity, Analytics Engine, other environments and external copies. D1/R2 operations are not one atomic transaction.
Respect source and deployed proof boundaries
Worked responses use the actual exported Worker, all nine D1 migrations and local R2. Auth, queue delivery and Analytics Engine are synthetic transports; local queue processing is explicitly invoked. Notify and Nexus are disabled. These examples do not prove live visitor collection, paid usage, notification delivery or hosted privacy erasure. The widget’s local raw-header grant gap is documented for remediation, not as an approved access path.