:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Product analytics agent guide
Insight access, sharing, and project scope
These rules apply when changing an insight endpoint, a bulk insight action, or a shared insight render.
Insights belong to a project, although the API serves them under an environment URL.
Read and write queries must use team__project_id=self.team.project_id where they operate on the insight set.
Do not restrict a project-level insight operation to only team_id=self.team_id.
Authorization contract
InsightViewSetfilters normallistreads through_filter_queryset_by_access_level. Custom list-like actions need an access-aware queryset implementation because this helper only filters whenself.action == "list".- Unsafe detail actions get object permission checks from the default
AccessControlPermissionchain. A new unsafe detail action keeps them as long as it goes throughget_object. - Detail-false bulk actions do not receive DRF object permissions. Filter every target through
_bulk_filter_editable_insights, or perform the equivalent per-insight editor check. Return skipped targets without changing them. - Restore access to an insight does not grant edit access to every dashboard that contains it. Use
restore_tiles_for_insightswithuser_access_control, so tiles remain hidden on dashboards the requester cannot edit. - For an action that supports personal API keys, OAuth, or MCP, declare
required_scopesor add it to the view set scope-action list. Otherwise, API-key callers receive a 403 response.
Shared-link contract
Sharing authentication only permits insight retrieve and list for insights connected to its sharing configuration.
Do not add write, mutation, or project-wide actions to sharing_enabled_actions.
When an insight renders with from_dashboard, use the shared configuration's dashboard ID to validate the tile. Do not use the requester's normal dashboard access in that path.
Insight variables cannot use sharing authentication. Keep this rejection in InsightVariableViewSet.initial for every variable action.
Where to make changes
- Read the insight API when changing access, sharing, bulk actions, or project scope.
- Read the insight-variable API when changing variable access.
- Extend the existing insight API tests for object access, shared links, or bulk access. Cover inaccessible targets and dashboard tiles that must remain hidden.
Insight deletion and related resources
These rules apply when changing insight deletion, restoration, or a resource attached to an insight.
An insight's normal deletion is a soft delete (deleted=True).
Setting that field does not invoke Django's on_delete=models.CASCADE, model delete() methods, or delete signals.
Foreign-key cascades only apply to hard deletion; soft deletion needs explicit related-resource cleanup.
Cleanup contract
Single and bulk insight deletion must apply the same cleanup in the transaction that marks the insight deleted:
| Related resource | Behavior when the insight is soft-deleted |
|---|---|
| Insight subscriptions, including paused and already soft-deleted subscriptions | Hard-delete through each subscription's delete() method; delivery history and contexts cascade. |
| Alert configurations | Hard-delete through each alert's delete() method. |
| Dashboard tiles containing the insight | Hide through hide_tiles_for_insights. Keep the dashboard itself. |
Only related resources within the authorized project scope may change. Deleting a subscription directly through its API remains a soft delete; deletion with its parent insight is permanent. Skipping delivery for a deleted insight does not replace deleting its subscriptions: surviving rows still appear in subscription management.
Restoring an insight does not recreate its subscriptions or alerts. Do not revive independently deleted related resources when adding or changing restore behavior.
Where to make changes
- Read the insight API when changing deletion or restore behavior.
InsightSerializer.updatehandles single deletion;InsightViewSet.bulk_deletebypasses model saves with a queryset update, so it must perform cleanup explicitly. - Read the subscriptions facade when changing subscription cleanup.
delete_insight_subscriptionscalls each subscription'sdelete()method so model activity logging runs. - Read the alerts facade when changing alert cleanup.
delete_insight_alertscalls each alert'sdelete()method to preserve activity logging; queryset deletion bypasses that override. - Read the dashboards facade when changing tile cleanup or restoration. Use
hide_tiles_for_insightsandrestore_tiles_for_insightsrather than duplicating their rules. - Extend the existing insight API tests when changing these behaviors. Cover single and bulk deletion, unrelated resources surviving, and restore behavior.
New deletion entry points, including background cleanup, must honor this contract.
Setting deleted=True through a model save or queryset update does not run the API's cleanup automatically.
When adding another related resource, define its deletion and restore behavior explicitly and apply it to both single and bulk operations.
Frontend placement
These rules apply when you add or move a frontend file for this product.
Frontend code that belongs to this product goes in products/product_analytics/frontend/, also when core imports it.
Do not put it in frontend/src/scenes/insights/ or in another scene tree that the placement report maps to this product.
resultSeriesName landed in scenes/insights/utils/ although only product files import it, so the default still points at core.
A file that another product also imports stays in core, for example scenes/insights/filters/ActionFilter/.
Products never import from each other, so a move would make that product import this one.
Core imports from this product are accepted.
The insight charts and the insight editor (frontend/insights/editor/) live here, and core's InsightViz and insight cards import them.
Merge-queue lanes come from paths only, so a change to such a file reports only this product's lane.
Master's post-merge run is the check for a conflict that this lets through.
Read the placement skill when you decide where a file goes.
Its scripts/scene_product_split.py is the placement report: it maps each scene tree to its product and shows how far the tree has moved.