: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import uuid
import dataclasses
from collections.abc import Callable, Sequence
from typing import ClassVar, Optional, cast
from django.http import Http404
import posthoganalytics
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import (
OpenApiParameter,
OpenApiResponse,
PolymorphicProxySerializer,
extend_schema,
extend_schema_field,
extend_schema_view,
)
from rest_framework import exceptions, filters, serializers, status, viewsets
from rest_framework.decorators import action
from rest_framework.exceptions import ValidationError
from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework.serializers import as_serializer_error
from rest_framework.throttling import BaseThrottle
from rest_framework.views import APIView
from posthog.api.forbid_destroy_model import ForbidDestroyModel
from posthog.api.ordering import StableOrderingFilter
from posthog.api.pagination import (
FacadeCursorPagination,
FacadeLimitOffsetPagination,
facade_cursor_page_response,
facade_page_response,
)
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.shared import UserBasicSerializer
from posthog.event_usage import get_request_analytics_properties, groups
from posthog.exceptions import QuotaLimitExceeded
from posthog.models.integer_field_bounds import INTEGER_FIELD_MAX, INTEGER_FIELD_MIN
from posthog.models.user import User
from posthog.permissions import is_service_auth
from posthog.rate_limit import SubscriptionTestDeliveryThrottle
from posthog.utils import str_to_bool
from products.access_control.backend.facade.contracts import ObjectAccessRef
from products.dashboards.backend.facade import api as dashboards_api
from products.product_analytics.backend.facade.models import Insight
from products.subscriptions.backend.facade import api, contracts
from products.subscriptions.backend.facade.api import (
AI_QUERY_PLAN_STATUS_CHOICES,
AI_REPORT_CHARTS_KEY,
AI_REPORT_DIAGNOSTICS_KEY,
AI_REPORT_PROMPT_SNAPSHOT_KEY,
AI_REPORT_QUERY_FAILURE_TYPE,
AI_REPORT_QUERY_PLAN_STATUS_KEY,
AI_REPORT_SNAPSHOT_KEY,
AI_WINDOW_MODE_CHOICES,
AI_WINDOW_MODE_LAST_N_DAYS,
AI_WINDOW_MODE_SINCE_LAST_SENT,
DELIVERY_STATUS_CHOICES,
FREQUENCY_CHOICES,
MAX_AI_SUBSCRIPTION_CONTEXTS,
MAX_INSIGHTS,
RESOURCE_TYPE_CHOICES,
TARGET_TYPE_CHOICES,
TARGET_TYPE_TEAMS,
WEEKDAY_CHOICES,
)
_AI_QUERY_PLAN_STATUS_VALUES = frozenset(value for value, _ in AI_QUERY_PLAN_STATUS_CHOICES)
_TARGET_TYPE_VALUES = [value for value, _ in TARGET_TYPE_CHOICES]
_DELIVERY_STATUS_VALUES = [value for value, _ in DELIVERY_STATUS_CHOICES]
# An agent reads one field's description in isolation, so every field repeats the scope rule.
_AI_DISPLAY_FIELD_SCOPE_NOTE = (
"The request is rejected when the subscription sets insight or dashboard instead of prompt. "
"It does not control the AI summary on an insight or dashboard subscription: use "
"summary_enabled and summary_prompt_guide for that."
)
def _insight_exists(insight_id: int) -> bool:
# The facade compares the insight's team with the request's team right after this check.
# nosemgrep: idor-lookup-without-team
return Insight.objects.filter(pk=insight_id).exists()
@extend_schema_field(OpenApiTypes.INT)
class _RelatedIdField(serializers.Field):
"""The id of an existing insight or dashboard, accepted and rejected the way a primary key
related field accepts and rejects it."""
default_error_messages = serializers.PrimaryKeyRelatedField.default_error_messages
def __init__(
self, *, exists: Callable[[int], bool], source: str, allow_null: bool, required: bool, help_text: str
) -> None:
self._exists = exists
super().__init__(source=source, allow_null=allow_null, required=required, help_text=help_text)
def run_validation(self, data: object = serializers.empty) -> object:
# Relational fields read an empty string as null.
if data == "":
data = None
return super().run_validation(data)
def to_internal_value(self, data: object) -> int:
try:
if isinstance(data, bool):
raise TypeError
pk = int(cast(str, data))
except (TypeError, ValueError):
self.fail("incorrect_type", data_type=type(data).__name__)
if not self._exists(pk):
self.fail("does_not_exist", pk_value=data)
return pk
def to_representation(self, value: int) -> int:
return value
@extend_schema_field({"type": "array", "items": {"type": "integer"}})
class DashboardExportInsightsField(serializers.Field):
"""Custom field to handle ManyToMany dashboard_export_insights as a list of IDs."""
def to_representation(self, value: Sequence[int]) -> list[int]:
return list(value)
def to_internal_value(self, data: object) -> list[int]:
if not isinstance(data, list):
raise serializers.ValidationError("Expected a list of insight IDs.")
for item in data:
if not isinstance(item, int):
raise serializers.ValidationError("All items must be integers.")
return data
class AIWindowConfigSerializer(serializers.Serializer):
mode = serializers.ChoiceField(
choices=AI_WINDOW_MODE_CHOICES,
default=AI_WINDOW_MODE_SINCE_LAST_SENT,
help_text=(
"What the report analyzes each run:\n"
"* `since_last_sent` (default) — everything since the previous successful scheduled delivery (gap-free; test/manual sends don't move the anchor)\n"
"* `last_n_days` — a fixed trailing window of start_days_ago days\n"
"* `days_ago_range` — the explicit range from start_days_ago to end_days_ago days ago"
),
)
start_days_ago = serializers.IntegerField(
required=False,
allow_null=True,
min_value=1,
max_value=365,
help_text=(
"Lower bound of the analysis window, in days before the run. Required for 'last_n_days' "
"(the N) and 'days_ago_range'; ignored for 'since_last_sent'. 1-365."
),
)
end_days_ago = serializers.IntegerField(
required=False,
allow_null=True,
min_value=0,
max_value=365,
help_text=(
"Upper bound of the analysis window, in days before the run (0 = now). Required for "
"'days_ago_range' and must be less than start_days_ago; ignored for other modes. 0-365."
),
)
def to_representation(self, instance: contracts.JsonValue) -> dict:
return api.normalize_ai_window(instance)
def validate(self, attrs: dict) -> dict:
mode = attrs.get("mode") or AI_WINDOW_MODE_SINCE_LAST_SENT
start = attrs.get("start_days_ago")
end = attrs.get("end_days_ago")
if mode == AI_WINDOW_MODE_SINCE_LAST_SENT:
# Day bounds are meaningless here; normalise them away so a later mode switch starts clean.
attrs["start_days_ago"] = None
attrs["end_days_ago"] = None
return attrs
if not start:
raise ValidationError({"start_days_ago": [f"Required when mode is '{mode}'."]})
if mode == AI_WINDOW_MODE_LAST_N_DAYS:
attrs["end_days_ago"] = None
return attrs
# DAYS_AGO_RANGE
if end is None:
raise ValidationError({"end_days_ago": [f"Required when mode is '{mode}'."]})
if end >= start:
raise ValidationError(
{"end_days_ago": ["Must be less than start_days_ago (the window must end after it starts)."]}
)
return attrs
class AIPromptConfigSerializer(serializers.Serializer):
window = AIWindowConfigSerializer(
required=False,
help_text="Analysis window for the report. Omitted = 'since_last_sent' (everything since the previous scheduled delivery).",
)
class DeliveryConfigSerializer(serializers.Serializer):
"""Typed view over the Subscription.delivery_config JSON blob."""
post_all_insights_in_main_message = serializers.BooleanField(
required=False,
default=False,
help_text=(
"Slack subscriptions only. Insight and dashboard subscriptions: when true, upload all insight "
"images together in the main Slack message instead of posting the first image in the main "
"message and the rest as threaded replies. Prompt subscriptions: when true, post the chart "
"images in the main message with the summary; when false, post them in the first thread "
"reply. Defaults to false. The request is rejected when target_type is not 'slack', or when "
"an insight or dashboard subscription's Slack integration does not hold the files:write "
"permission. "
"Omit it unless the user asks for all images or charts in the main message."
),
)
include_images = serializers.BooleanField(
required=False,
help_text="Prompt subscriptions only: include generated chart images. Defaults to true when omitted. "
+ _AI_DISPLAY_FIELD_SCOPE_NOTE,
)
include_feedback = serializers.BooleanField(
required=False,
help_text="Prompt subscriptions only: include report feedback links. Defaults to true when omitted. "
+ _AI_DISPLAY_FIELD_SCOPE_NOTE,
)
include_manage_link = serializers.BooleanField(
required=False,
help_text="Prompt subscriptions only: include a link to manage the subscription. "
"Defaults to true when omitted. " + _AI_DISPLAY_FIELD_SCOPE_NOTE,
)
include_posthog_hint = serializers.BooleanField(
required=False,
help_text="Prompt subscriptions only: include PostHog product guidance. Defaults to true when "
"omitted. Only a Slack report renders the guidance. Email and Microsoft Teams reports leave it "
"out and accept the option without an error, unlike post_all_insights_in_main_message. "
+ _AI_DISPLAY_FIELD_SCOPE_NOTE,
)
class SubscriptionContextWriteSerializer(serializers.Serializer):
dashboard_id = serializers.IntegerField(
required=False,
min_value=1,
help_text="Dashboard ID to use as AI report context. Set either dashboard_id or insight_id, not both.",
)
insight_id = serializers.IntegerField(
required=False,
min_value=1,
help_text="Insight ID to use as AI report context. Set either insight_id or dashboard_id, not both.",
)
def validate(self, attrs: dict) -> dict:
if ("dashboard_id" in attrs) == ("insight_id" in attrs):
raise ValidationError("Set exactly one of dashboard_id or insight_id.")
return attrs
@extend_schema_field(
{
"type": "array",
"maxItems": MAX_AI_SUBSCRIPTION_CONTEXTS,
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": False,
"required": ["dashboard_id"],
"properties": {"dashboard_id": {"type": "integer", "minimum": 1}},
},
{
"type": "object",
"additionalProperties": False,
"required": ["insight_id"],
"properties": {"insight_id": {"type": "integer", "minimum": 1}},
},
]
},
}
)
class SubscriptionContextsWriteField(serializers.ListField):
pass
class SubscriptionDashboardContextSerializer(serializers.Serializer):
dashboard_id = serializers.IntegerField(help_text="Dashboard ID used to open the context dashboard.")
dashboard_name = serializers.CharField(help_text="Current display name of the context dashboard.")
class SubscriptionInsightContextSerializer(serializers.Serializer):
insight_id = serializers.IntegerField(help_text="Database ID of the context insight.")
insight_short_id = serializers.CharField(help_text="Stable insight identifier used to open the context insight.")
insight_name = serializers.CharField(help_text="Current display name of the context insight.")
SUBSCRIPTION_CONTEXT_READ_SCHEMA = PolymorphicProxySerializer(
component_name="SubscriptionContext",
serializers=[SubscriptionDashboardContextSerializer, SubscriptionInsightContextSerializer],
resource_type_field_name=None,
many=True,
)
# Field order of the subscription serializers, which the generated types follow.
_SUBSCRIPTION_FIELDS = (
"id",
"resource_type",
"dashboard",
"insight",
"insight_short_id",
"resource_name",
"dashboard_export_insights",
"prompt",
"ai_prompt_config",
"contexts",
"ai_query_plan_status",
"target_type",
"target_value",
"frequency",
"interval",
"byweekday",
"bysetpos",
"count",
"start_date",
"until_date",
"created_at",
"created_by",
"deleted",
"enabled",
"title",
"summary",
"next_delivery_date",
"integration_id",
"invite_message",
"send_test_now",
"summary_enabled",
"summary_prompt_guide",
"delivery_config",
)
class SubscriptionWriteSerializer(serializers.Serializer):
"""Standard Subscription serializer."""
id = serializers.IntegerField(read_only=True)
resource_type = serializers.ChoiceField(
choices=RESOURCE_TYPE_CHOICES,
read_only=True,
help_text=(
"What the subscription delivers: 'insight' (snapshot of one insight), "
"'dashboard' (snapshot of one dashboard), or 'ai_prompt' (LLM-generated report). "
"Read-only — derived from the populated target (insight → insight, "
"dashboard → dashboard, prompt → ai_prompt)."
),
)
dashboard = _RelatedIdField(
exists=dashboards_api.dashboard_exists,
source="dashboard_id",
allow_null=True,
required=False,
help_text="Dashboard ID to subscribe to (mutually exclusive with insight on create).",
)
insight = _RelatedIdField(
exists=_insight_exists,
source="insight_id",
allow_null=True,
required=False,
help_text="Insight ID to subscribe to (mutually exclusive with dashboard on create).",
)
insight_short_id = serializers.SerializerMethodField()
resource_name = serializers.SerializerMethodField()
dashboard_export_insights = DashboardExportInsightsField(
source="dashboard_export_insight_ids",
required=False,
help_text=f"List of insight IDs from the dashboard to include. Required for dashboard subscriptions, max {MAX_INSIGHTS}.",
)
prompt = serializers.CharField(
allow_blank=True,
allow_null=True,
required=False,
style={"base_template": "textarea.html"},
help_text=(
"Free-text prompt that drives the AI-generated report. Required when "
"resource_type is 'ai_prompt'. Max 4000 characters."
),
)
ai_prompt_config = AIPromptConfigSerializer(
required=False,
help_text=(
"Configuration for AI report subscriptions (analysis window, future knobs). Only valid "
"when resource_type is 'ai_prompt'. Replaced wholesale on writes."
),
)
contexts: serializers.Field = SubscriptionContextsWriteField(
child=SubscriptionContextWriteSerializer(),
required=False,
write_only=True,
help_text=(
"Complete dashboard and insight context for an AI report. Omit on PATCH to preserve, pass an empty "
f"list to clear, or pass up to {MAX_AI_SUBSCRIPTION_CONTEXTS} items to replace all contexts."
),
)
ai_query_plan_status = serializers.SerializerMethodField(
help_text=(
"Query plan reuse state for AI prompt subscriptions: frozen, not_frozen, or planner_updated. "
"Null for other subscription types."
)
)
target_type = serializers.ChoiceField(
choices=TARGET_TYPE_CHOICES, help_text="Delivery channel: email, slack, or teams."
)
target_value = serializers.CharField(
style={"base_template": "textarea.html"},
help_text=(
"Recipient(s): comma-separated email addresses for email, Slack channel name/ID for slack, "
"or a Microsoft Teams webhook URL for teams. A Teams webhook URL is only ever returned as "
"its host, because the URL authorizes a post to the channel by itself. On update, omit the "
"field to keep the stored URL, or send a full URL to replace it."
),
)
frequency = serializers.ChoiceField(
choices=FREQUENCY_CHOICES, help_text="How often to deliver: daily, weekly, monthly, or yearly."
)
interval = serializers.IntegerField(
required=True,
min_value=1,
max_value=INTEGER_FIELD_MAX,
help_text=(
"Interval multiplier (e.g. 2 with weekly frequency means every 2 weeks). "
"Required on create; must be 1 or greater."
),
)
byweekday = serializers.ListField(
child=serializers.ChoiceField(choices=WEEKDAY_CHOICES),
allow_null=True,
required=False,
help_text="Days of week for daily or weekly subscriptions: monday, tuesday, wednesday, thursday, friday, saturday, sunday.",
)
bysetpos = serializers.IntegerField(
allow_null=True,
required=False,
min_value=INTEGER_FIELD_MIN,
max_value=INTEGER_FIELD_MAX,
help_text="Position within byweekday set for monthly frequency (e.g. 1 for first, -1 for last).",
)
count = serializers.IntegerField(
allow_null=True,
required=False,
min_value=INTEGER_FIELD_MIN,
max_value=INTEGER_FIELD_MAX,
help_text="Total number of deliveries before the subscription stops. Null for unlimited.",
)
start_date = serializers.DateTimeField(
help_text=(
"When to start delivering (ISO 8601 datetime). The date anchors the recurrence and may be in "
"the past. Deliveries run on half-hour cycles at :00 and :30. Other minute values are accepted "
"for backward compatibility, but delivery happens during the next cycle instead of at that exact minute."
)
)
until_date = serializers.DateTimeField(
allow_null=True,
required=False,
help_text="When to stop delivering (ISO 8601 datetime). Null for indefinite.",
)
created_at = serializers.DateTimeField(read_only=True)
created_by = UserBasicSerializer(read_only=True)
deleted = serializers.BooleanField(
required=False, help_text="Set to true to soft-delete. Subscriptions cannot be hard-deleted."
)
enabled = serializers.BooleanField(
required=False,
help_text="Whether the subscription is active. Set to false to pause delivery without deleting. Auto-set to false when the delivery integration becomes invalid.",
)
title = serializers.CharField(
allow_blank=True,
allow_null=True,
required=False,
max_length=100,
help_text="Human-readable name for this subscription.",
)
summary = serializers.CharField(read_only=True, help_text="Human-readable schedule summary, e.g. 'sent daily'.")
next_delivery_date = serializers.DateTimeField(allow_null=True, read_only=True)
integration_id = serializers.IntegerField(
required=False,
allow_null=True,
help_text="ID of a connected Slack integration. Required when target_type is slack.",
)
invite_message = serializers.CharField(
required=False,
allow_blank=True,
allow_null=True,
help_text="Optional message included in the invitation email when adding new recipients.",
)
send_test_now = serializers.BooleanField(
required=False,
write_only=True,
help_text=(
"Whether to immediately deliver the subscription once on save so the editor can confirm "
"it looks right. Defaults to true on create. When omitted on update, a delivery is sent "
"only if the edit changed what gets delivered (recipient, channel, source) or re-enabled "
"the subscription. The recurring schedule is unaffected."
),
)
summary_enabled = serializers.BooleanField(
required=False,
help_text=(
"Whether to attach an AI-generated summary to each delivery (insight and dashboard "
"subscriptions only). Requires the organization to have approved AI data processing, and "
"is subject to the org's active-summary cap and AI credit budget; otherwise the write is "
"rejected. Not applicable to prompt subscriptions, which are themselves AI-generated."
),
)
summary_prompt_guide = serializers.CharField(
allow_blank=True,
required=False,
max_length=500,
help_text=(
"Optional free-text guidance (max 500 chars) steering the AI summary, e.g. which metrics "
"to emphasize. Only settable when AI summary context is enabled for the organization; "
"clearing it (empty string) is always allowed."
),
)
delivery_config = DeliveryConfigSerializer(
required=False,
help_text=(
"Per-delivery rendering options. Every option applies to one subscription kind or delivery "
"target only, and each option's own description says where it applies and whether a "
"mismatch is rejected or ignored. Omit this field unless the user asks for one of the "
"options."
),
)
def get_fields(self) -> dict[str, serializers.Field]:
fields = super().get_fields()
return {name: fields[name] for name in _SUBSCRIPTION_FIELDS}
def get_insight_short_id(self, obj: contracts.SubscriptionRecord) -> Optional[str]:
return obj.insight_short_id
def get_resource_name(self, obj: contracts.SubscriptionRecord) -> Optional[str]:
return obj.resource_name
@extend_schema_field(
serializers.ChoiceField(
choices=AI_QUERY_PLAN_STATUS_CHOICES,
allow_null=True,
)
)
def get_ai_query_plan_status(self, subscription: contracts.SubscriptionRecord) -> Optional[str]:
return subscription.ai_query_plan_status
def to_representation(self, instance: contracts.SubscriptionRecord) -> dict:
representation = super().to_representation(instance)
if instance.target_type == TARGET_TYPE_TEAMS:
representation["target_value"] = instance.recipient_label
return representation
def to_write(self) -> contracts.SubscriptionWrite:
values = dict(self.validated_data)
if "contexts" in values:
values["contexts"] = tuple(
contracts.SubscriptionContextTarget(kind="dashboard", id=context["dashboard_id"])
if "dashboard_id" in context
else contracts.SubscriptionContextTarget(kind="insight", id=context["insight_id"])
for context in values["contexts"]
)
# The fields' sources name the SubscriptionWrite fields, so validated data maps onto it one to one.
return contracts.SubscriptionWrite(**values)
class SubscriptionSerializer(SubscriptionWriteSerializer):
contexts: serializers.Field = serializers.SerializerMethodField(
help_text="Dashboards and insights that ground this AI report. Deleted resources are omitted."
)
@extend_schema_field(SUBSCRIPTION_CONTEXT_READ_SCHEMA)
def get_contexts(self, obj: contracts.SubscriptionRecord) -> list[dict[str, str | int]]:
contexts: list[dict[str, str | int]] = []
for context in obj.contexts:
if isinstance(context, contracts.SubscriptionDashboardContext):
contexts.append({"dashboard_id": context.dashboard_id, "dashboard_name": context.dashboard_name})
else:
contexts.append(
{
"insight_id": context.insight_id,
"insight_short_id": context.insight_short_id,
"insight_name": context.insight_name,
}
)
return contexts
def _write_response(subscription: contracts.SubscriptionRecord, *, partial: bool) -> dict:
# A write answers with its contexts last, after the fields the request itself can set. A partial
# write leaves out the defaults of nested fields the stored value does not hold.
data = dict(SubscriptionSerializer(subscription, partial=partial).data)
data["contexts"] = data.pop("contexts")
return data
def _parse_int_param(value: str, param: str) -> int:
try:
return int(value.strip())
except ValueError:
raise ValidationError({param: ["Must be an integer ID."]}) from None
def _parse_int_list_param(value: str, param: str) -> list[int]:
# int() (not str.isdigit) so exotic digits like "²" fail as a 400 here instead of a 500,
# and invalid tokens reject the request instead of being silently dropped.
tokens = [token.strip() for token in value.split(",") if token.strip()]
try:
ids = [int(token) for token in tokens]
except ValueError:
ids = []
if not ids:
raise ValidationError({param: ["Must be a comma-separated list of integer insight IDs."]})
return ids
def _raise_for_refusal(call: Callable[[], contracts.SubscriptionRecord]) -> contracts.SubscriptionRecord:
"""Run a subscription write, and answer each refusal the way a serializer's validate() would."""
try:
return call()
except contracts.SubscriptionRequestInvalidError as refusal:
raise ValidationError(as_serializer_error(ValidationError(refusal.detail, code=refusal.code)))
except contracts.SubscriptionPermissionDeniedError as refusal:
raise exceptions.PermissionDenied(refusal.message)
except contracts.SubscriptionQuotaExceededError as refusal:
raise QuotaLimitExceeded(refusal.message)
class SubscriptionSummariesQuerySerializer(serializers.Serializer):
insight = serializers.IntegerField(
required=False,
min_value=1,
help_text="Insight ID. Returns summaries from the subscriptions on this insight. Set either insight or dashboard.",
)
dashboard = serializers.IntegerField(
required=False,
min_value=1,
help_text="Dashboard ID. Returns summaries from the subscriptions on this dashboard. Set either dashboard or insight.",
)
def validate(self, attrs: dict) -> dict:
if ("insight" in attrs) == ("dashboard" in attrs):
raise ValidationError("Set exactly one of insight or dashboard.")
return attrs
class SubscriptionSummarySerializer(serializers.Serializer):
id = serializers.UUIDField(read_only=True, help_text="ID of the delivery that included this summary.")
subscription = serializers.IntegerField(
source="subscription_id", read_only=True, help_text="ID of the subscription that generated this summary."
)
subscription_title = serializers.CharField(
allow_null=True,
read_only=True,
help_text="Title of the subscription that generated this summary. Null when the subscription has no title.",
)
target_type = serializers.CharField(
read_only=True, help_text="Channel the summary was sent to: email, slack, or teams."
)
change_summary = serializers.CharField(
allow_null=True, read_only=True, help_text="AI-generated summary text included in the delivery."
)
period_start = serializers.DateTimeField(
allow_null=True,
read_only=True,
help_text=(
"Start of the period this summary covers: the time of the previous completed delivery of the same "
"subscription. Null for the first delivery, which has no earlier data to compare with."
),
)
created_at = serializers.DateTimeField(
read_only=True, help_text="When the delivery started. This is also the end of the covered period."
)
class SubscriptionSummaryCursorPagination(FacadeCursorPagination):
page_size = 20
ordering = "-created_at"
_SUBSCRIPTION_ID_PARAMETER = OpenApiParameter(
"id",
OpenApiTypes.INT,
OpenApiParameter.PATH,
description="A unique integer value identifying this subscription.",
)
@extend_schema_view(
list=extend_schema(
extensions={"x-product": "subscriptions"},
parameters=[
OpenApiParameter(
name="created_by",
type=str,
location=OpenApiParameter.QUERY,
required=False,
description="Filter by creator user UUID.",
),
OpenApiParameter(
name="resource_type",
type=str,
enum=["insight", "dashboard", "ai_prompt"],
location=OpenApiParameter.QUERY,
required=False,
description="Filter by subscription resource: insight, dashboard export, or AI report.",
),
OpenApiParameter(
name="target_type",
type=str,
enum=_TARGET_TYPE_VALUES,
location=OpenApiParameter.QUERY,
required=False,
description="Filter by delivery channel: email, Slack, or Microsoft Teams.",
),
OpenApiParameter(
name="insight",
type=int,
location=OpenApiParameter.QUERY,
required=False,
description="Filter by insight ID.",
),
OpenApiParameter(
name="insights",
type=str,
location=OpenApiParameter.QUERY,
required=False,
description="Filter by a comma-separated list of insight IDs.",
),
OpenApiParameter(
name="dashboard",
type=int,
location=OpenApiParameter.QUERY,
required=False,
description="Filter by dashboard ID.",
),
OpenApiParameter(
name="dashboard_tiles",
type=int,
location=OpenApiParameter.QUERY,
required=False,
description="Filter to subscriptions on insights that are tiles of the given dashboard ID.",
),
],
),
create=extend_schema(
request=SubscriptionWriteSerializer,
responses={201: SubscriptionSerializer},
extensions={"x-product": "subscriptions"},
),
retrieve=extend_schema(parameters=[_SUBSCRIPTION_ID_PARAMETER], extensions={"x-product": "subscriptions"}),
update=extend_schema(
parameters=[_SUBSCRIPTION_ID_PARAMETER],
request=SubscriptionWriteSerializer,
responses={200: SubscriptionSerializer},
extensions={"x-product": "subscriptions"},
),
partial_update=extend_schema(
parameters=[_SUBSCRIPTION_ID_PARAMETER],
request=SubscriptionWriteSerializer,
responses={200: SubscriptionSerializer},
extensions={"x-product": "subscriptions"},
),
destroy=extend_schema(parameters=[_SUBSCRIPTION_ID_PARAMETER], extensions={"x-product": "subscriptions"}),
)
@extend_schema(tags=["subscriptions"], extensions={"x-product": "subscriptions"})
class SubscriptionViewSet(TeamAndOrgViewSetMixin, ForbidDestroyModel, viewsets.GenericViewSet):
scope_object = "subscription"
serializer_class = SubscriptionSerializer
pagination_class = FacadeLimitOffsetPagination
filter_backends = [filters.SearchFilter, StableOrderingFilter]
ordering_fields = [
"created_at",
"next_delivery_date",
"title",
"created_by__email",
]
ordering = ["-created_at"]
def get_serializer_class(self) -> type[serializers.Serializer]:
if self.action in ("create", "update", "partial_update"):
return SubscriptionWriteSerializer
return SubscriptionSerializer
# Writing an AI prompt subscription also requires query-read access: it runs LLM-generated
# HogQL and delivers the results, so subscription:write alone could exfiltrate analytics.
# Two layers gate this off _write_touches_ai_subscription: a required query:read scope keeps a
# token least-privileged, and the RBAC check in check_permissions enforces actual query access
# for every write — a scope is only a capability flag, not proof of RBAC (personal keys can
# carry query:read without it), and session auth has no scopes at all.
def dangerously_get_required_scopes(self, request: Request, view: APIView) -> list[str] | None:
if request.method in ("GET", "HEAD", "OPTIONS"):
return None
scopes = [f"{self.scope_object}:write"]
if self._write_touches_ai_subscription(request, view):
scopes.append("query:read")
return scopes
def check_permissions(self, request: Request) -> None:
super().check_permissions(request)
# Enforce query-viewer RBAC for every AI-prompt write, regardless of auth: the query:read
# scope above gates tokens but does not prove the owner has query access, and session auth
# bypasses scopes entirely.
if (
request.method not in ("GET", "HEAD", "OPTIONS")
and self._write_touches_ai_subscription(request, self)
and not self.user_access_control.check_access_level_for_resource("query", "viewer")
):
raise exceptions.PermissionDenied("You need query access to create or deliver AI prompt subscriptions.")
def _write_touches_ai_subscription(self, request: Request, view: APIView) -> bool:
if request.data.get("prompt"): # create (or a body that sets a prompt)
return True
# Existing subscription (update / test-delivery): resolve its kind by pk, team-scoped.
pk = view.kwargs.get("pk")
return bool(pk) and api.is_ai_prompt_subscription(team_id=self.team_id, subscription_id=pk)
def get_throttles(self) -> list[BaseThrottle]:
throttles = super().get_throttles()
# An update that requests send_test_now enqueues a real email/Slack delivery — the same
# blast radius as the test-delivery action — so it shares that team-wide throttle.
data = self.request.data
if self.action in ("update", "partial_update") and isinstance(data, dict) and data.get("send_test_now"):
throttles.append(SubscriptionTestDeliveryThrottle())
return throttles
def _dashboard_tile_insight_ids(self, value: str) -> tuple[int, ...]:
# Subscriptions on insights that are live tiles of the given dashboard, resolved server-side
# so the overview's "Insights" tab never depends on which tiles the client happens to have
# loaded into memory. Deleted tiles, dashboards and insights do not count, matching the tile
# set the sibling dashboard-export validation resolves.
dashboard_id = _parse_int_param(value, "dashboard_tiles")
# Require view access to the dashboard itself: without it a project member could pass any
# dashboard ID and enumerate which subscribed insights are tiles on a dashboard they can't see.
try:
dashboards_api.viewable_dashboard_id(
team_id=self.team_id, dashboard_id=dashboard_id, user_access_control=self.user_access_control
)
except dashboards_api.DashboardNotFound:
raise ValidationError({"dashboard_tiles": ["Dashboard not found."]})
except dashboards_api.DashboardNotViewable:
raise exceptions.PermissionDenied("You do not have access to this dashboard.")
return tuple(dashboards_api.live_tile_insight_ids(dashboard_id))
def _subscription_filters(self) -> contracts.SubscriptionFilters:
"""The query parameters every subscription route narrows by, the list and single rows alike."""
request_params = self.request.GET.dict()
insight_ids: tuple[int, ...] | None = None
any_of_insight_ids: tuple[int, ...] | None = None
tile_insight_ids: tuple[int, ...] | None = None
dashboard_id: int | None = None
deleted: bool | None = False if self.action == "list" and "deleted" not in request_params else None
for key in request_params:
if key == "insight":
# `insight` (single ID) and `insights` (comma-separated IDs) share one parser, so
# behavior and validation stay identical.
insight_ids = tuple(_parse_int_list_param(request_params[key], key))
elif key == "insights":
any_of_insight_ids = tuple(_parse_int_list_param(request_params[key], key))
elif key == "dashboard_tiles":
tile_insight_ids = self._dashboard_tile_insight_ids(request_params[key])
elif key == "dashboard":
dashboard_id = _parse_int_param(request_params["dashboard"], "dashboard")
elif key == "deleted":
deleted = str_to_bool(request_params["deleted"])
return contracts.SubscriptionFilters(
insight_ids=insight_ids,
any_of_insight_ids=any_of_insight_ids,
tile_insight_ids=tile_insight_ids,
dashboard_id=dashboard_id,
deleted=deleted,
search_terms=tuple(filters.SearchFilter().get_search_terms(self.request)),
)
def _get_subscription(self) -> contracts.SubscriptionRef:
try:
subscription = api.get_subscription_ref(
team_id=self.team_id,
subscription_id=self.kwargs["pk"],
filters=self._subscription_filters(),
viewer=self.user_access_control,
)
except contracts.SubscriptionNotFoundError:
raise Http404("No Subscription matches the given query.")
except contracts.SubscriptionPermissionDeniedError as denied:
raise exceptions.PermissionDenied(denied.message)
self.check_object_permissions(
self.request,
ObjectAccessRef(
resource="subscription",
id=str(subscription.id),
team_id=subscription.team_id,
created_by_id=subscription.created_by_id,
),
)
return subscription
def list(self, request: Request, **kwargs: object) -> Response:
request_params = request.GET.dict()
created_by = request_params.get("created_by")
if created_by:
try:
uuid.UUID(created_by)
except ValueError:
raise ValidationError({"created_by": ["Not a valid UUID."]}) from None
target_type = request_params.get("target_type")
if target_type and target_type not in _TARGET_TYPE_VALUES:
raise ValidationError({"target_type": [f"Must be one of: {', '.join(sorted(_TARGET_TYPE_VALUES))}."]})
query = contracts.SubscriptionListQuery(
filters=self._subscription_filters(),
created_by_uuid=created_by or None,
resource_type=request_params.get("resource_type"),
target_type=target_type or None,
ordering=tuple(StableOrderingFilter().get_ordering(request, None, self) or ()),
filter_by_object_access=not is_service_auth(request),
include_all_if_admin=request.GET.get("admin_include_all") == "true",
)
return facade_page_response(
self,
lambda page: api.list_subscriptions(
team_id=self.team_id, query=query, viewer=self.user_access_control, page=page
),
)
def retrieve(self, request: Request, **kwargs: object) -> Response:
subscription = self._get_subscription()
return Response(
self.get_serializer(api.get_subscription(team_id=self.team_id, subscription_id=subscription.id)).data
)
def create(self, request: Request, **kwargs: object) -> Response:
serializer = cast(SubscriptionWriteSerializer, self.get_serializer(data=request.data))
serializer.is_valid(raise_exception=True)
subscription = _raise_for_refusal(
lambda: api.create_subscription(
team=self.team,
organization=self.organization,
user=cast(User, request.user),
viewer=self.user_access_control,
write=serializer.to_write(),
analytics_props=get_request_analytics_properties(request),
)
)
return Response(_write_response(subscription, partial=False), status=status.HTTP_201_CREATED)
def update(self, request: Request, partial: bool = False, **kwargs: object) -> Response:
subscription = self._get_subscription()
serializer = cast(SubscriptionWriteSerializer, self.get_serializer(data=request.data, partial=partial))
serializer.is_valid(raise_exception=True)
updated = _raise_for_refusal(
lambda: api.update_subscription(
team=self.team,
organization=self.organization,
user=cast(User, request.user),
viewer=self.user_access_control,
subscription_id=subscription.id,
write=serializer.to_write(),
partial=partial,
analytics_props=get_request_analytics_properties(request),
)
)
return Response(_write_response(updated, partial=partial))
def partial_update(self, request: Request, **kwargs: object) -> Response:
return self.update(request, partial=True, **kwargs)
@extend_schema(
extensions={"x-product": "subscriptions"},
request=None,
responses={200: SubscriptionSerializer},
description=(
"Make the requesting user the owner of this subscription and enable it. Deliveries run with "
"the owner's access, so this is how a subscription continues after its owner left."
),
)
# Scope is resolved dynamically in dangerously_get_required_scopes so an AI subscription also
# requires query:read (enabling it starts the AI HogQL pipeline). A static required_scopes here
# would short-circuit that check.
@action(methods=["POST"], detail=True)
def take_ownership(self, request: Request, **kwargs: object) -> Response:
subscription = self._get_subscription()
if subscription.deleted:
return Response(status=status.HTTP_404_NOT_FOUND)
updated = _raise_for_refusal(
lambda: api.take_subscription_ownership(
team=self.team,
organization=self.organization,
user=cast(User, request.user),
viewer=self.user_access_control,
subscription_id=subscription.id,
analytics_props=get_request_analytics_properties(request),
)
)
return Response(_write_response(updated, partial=True))
@extend_schema(
extensions={"x-product": "subscriptions"},
request=None,
responses={
200: OpenApiResponse(
description=(
"Org-wide AI summary quota: count of currently-active summaries and the limit "
"for the org's plan tier. `limit` is null when no cap is configured."
),
response={
"type": "object",
"properties": {
"active_count": {"type": "integer"},
"limit": {"type": "integer", "nullable": True},
"at_limit": {"type": "boolean"},
},
"required": ["active_count", "limit", "at_limit"],
},
)
},
)
@action(
methods=["GET"],
detail=False,
url_path="summary_quota",
required_scopes=["subscription:read"],
)
def summary_quota(self, request: Request, **kwargs: object) -> Response:
return Response(dataclasses.asdict(api.get_summary_quota(self.organization)))
@extend_schema(
extensions={"x-product": "subscriptions"},
summary="List AI summaries for an insight or dashboard",
description=(
"Completed deliveries that include an AI summary, across every active subscription on one insight or "
"dashboard, newest first. Requires viewer access to the insight or dashboard."
),
parameters=[SubscriptionSummariesQuerySerializer],
responses={200: SubscriptionSummarySerializer(many=True)},
)
@action(
methods=["GET"],
detail=False,
url_path="summaries",
required_scopes=["subscription:read"],
pagination_class=SubscriptionSummaryCursorPagination,
filter_backends=[],
)
def summaries(self, request: Request, **kwargs: object) -> Response:
query = SubscriptionSummariesQuerySerializer(data=request.query_params)
query.is_valid(raise_exception=True)
insight_id: int | None = None
dashboard_id: int | None = None
if "insight" in query.validated_data:
try:
insight_id = api.viewable_live_insight_id(
team_id=self.team_id, insight_id=query.validated_data["insight"], viewer=self.user_access_control
)
except contracts.SubscriptionNotFoundError:
raise exceptions.NotFound()
except contracts.SubscriptionPermissionDeniedError as denied:
raise exceptions.PermissionDenied(denied.message)
else:
try:
dashboard_id = dashboards_api.viewable_dashboard_id(
team_id=self.team_id,
dashboard_id=query.validated_data["dashboard"],
user_access_control=self.user_access_control,
)
except dashboards_api.DashboardNotFound:
raise Http404("No Dashboard matches the given query.")
except dashboards_api.DashboardNotViewable:
raise exceptions.PermissionDenied("You do not have access to this resource.")
return facade_cursor_page_response(
self,
lambda page: api.list_subscription_summaries(
team_id=self.team_id,
insight_id=insight_id,
dashboard_id=dashboard_id,
viewer=self.user_access_control,
page=page,
),
serializer_class=SubscriptionSummarySerializer,
)
@extend_schema(
extensions={"x-product": "subscriptions"},
parameters=[_SUBSCRIPTION_ID_PARAMETER],
request=None,
responses={202: OpenApiResponse(description="Test delivery workflow started")},
)
# nosemgrep: api-path-underscore -- shipped public API path, a rename breaks clients
@action(
methods=["POST"],
detail=True,
url_path="test-delivery",
throttle_classes=[SubscriptionTestDeliveryThrottle],
# Scope is resolved dynamically in dangerously_get_required_scopes so AI subscriptions
# also require query:read (test-delivery runs the AI HogQL pipeline). A static
# required_scopes here would short-circuit that check.
)
def test_delivery(self, request: Request, **kwargs: object) -> Response:
subscription = self._get_subscription()
if subscription.deleted:
return Response(status=status.HTTP_404_NOT_FOUND)
if not subscription.enabled:
return Response(
{"detail": "Subscription is disabled. Re-enable it before sending a test delivery."},
status=status.HTTP_409_CONFLICT,
)
result = api.start_test_delivery(team_id=self.team_id, subscription_id=subscription.id)
if result.outcome == contracts.ManualDeliveryOutcome.ALREADY_RUNNING:
return Response(
{"detail": "Delivery already in progress"},
status=status.HTTP_409_CONFLICT,
)
if result.outcome == contracts.ManualDeliveryOutcome.FAILED:
return Response(
{"detail": "Failed to schedule delivery"},
status=status.HTTP_500_INTERNAL_SERVER_ERROR,
)
posthoganalytics.capture(
distinct_id=str(cast(User, request.user).distinct_id),
event="subscription_test_delivery_scheduled",
properties={
**get_request_analytics_properties(request),
"subscription_id": subscription.id,
"team_id": subscription.team_id,
"target_type": subscription.target_type,
"insight_id": subscription.insight_id,
"dashboard_id": subscription.dashboard_id,
"temporal_workflow_id": result.workflow_id,
},
groups=groups(None, self.team),
)
return Response(status=status.HTTP_202_ACCEPTED)
class AIReportChartSerializer(serializers.Serializer):
export_asset_id = serializers.IntegerField(help_text="Id of the rendered PNG export backing this chart.")
title = serializers.CharField(help_text="Chart caption, taken from the plan step it illustrates.")
step_index = serializers.IntegerField(help_text="Index of the plan step this chart came from.")
class AIReportQueryDiagnosticSerializer(serializers.Serializer):
# Per-step query diagnostics persisted alongside the report markdown. Query-derived (the generated
# HogQL is here), so it is scrubbed for callers without query access — never shipped to recipients.
description = serializers.CharField(help_text="What this query step was meant to compute.")
hogql = serializers.CharField(help_text="The HogQL the assistant generated for this step.")
ok = serializers.BooleanField(help_text="Whether the query ran successfully.")
error_type = serializers.CharField(
allow_null=True, help_text="Exception class name when the query failed; null on success."
)
error_code = serializers.CharField(
allow_null=True,
required=False,
help_text="Stable query API error code when available; null on success and for unclassified errors.",
)
human_readable_error = serializers.CharField(
allow_null=True,
required=False,
help_text="Human-readable failure reason, present only for query errors safe to surface to the "
"subscription owner (e.g. an unresolved field name); null on success and for internal errors, "
"which expose error_type only.",
)
class SubscriptionDeliverySerializer(serializers.Serializer):
AI_REPORT_SCRUBBED_ERROR = {
"type": AI_REPORT_QUERY_FAILURE_TYPE,
"message": "The report could not be computed.",
}
# Delivery fields that embed the query-derived AI report, mapped to the value each returns when
# scrubbed for a caller without query access (content_snapshot is a non-null object, the rest
# nullable). Single source of truth — keep in sync when adding AI-derived delivery fields.
# ai_report_prompt is user-authored (not query-derived) and already readable on the parent
# subscription, so it is intentionally not scrubbed.
# ai_query_plan_status is harmless execution metadata, so it also stays visible without query access.
# recipient_results is also intentionally not scrubbed: its human_readable_error values are
# audience-independent delivery failure reasons (auto-disable causes, prompt rejections, Slack
# thread-failure counts) that carry no query-derived data. New producers of
# recipient_results[].human_readable_error must keep that invariant — never route a
# query/executor-derived message through it, since query-restricted viewers can read it.
AI_REPORT_SCRUBBED: ClassVar[dict[str, object | None]] = {
"content_snapshot": {},
"change_summary": None,
"ai_report": None,
"ai_report_diagnostics": None,
"ai_report_charts": None,
}
id = serializers.UUIDField(read_only=True, help_text="Primary key for this delivery row.")
subscription = serializers.IntegerField(
source="subscription_id", read_only=True, help_text="Parent subscription id."
)
temporal_workflow_id = serializers.CharField(
read_only=True, help_text="Temporal workflow id for this delivery run."
)
idempotency_key = serializers.CharField(
read_only=True, help_text="Dedupes activity retries for the same logical run."
)
trigger_type = serializers.CharField(
read_only=True, help_text="Why the run started (e.g. scheduled, manual, subscription update)."
)
scheduled_at = serializers.DateTimeField(
allow_null=True, read_only=True, help_text="Planned send time when applicable."
)
target_type = serializers.CharField(
read_only=True, help_text="Channel snapshot at send time: email, slack, or teams."
)
target_value = serializers.CharField(
read_only=True,
help_text=(
"Destination snapshot at send time: the email list, the Slack channel id, or the "
"host of the Microsoft Teams webhook. The webhook URL itself is never returned."
),
)
exported_asset_ids = serializers.ListField(
child=serializers.IntegerField(min_value=INTEGER_FIELD_MIN, max_value=INTEGER_FIELD_MAX),
allow_empty=False,
read_only=True,
help_text="ExportedAsset ids generated for this send.",
)
content_snapshot = serializers.JSONField(
read_only=True,
help_text=(
"Snapshot at send time: dashboard metadata, total_insight_count, and per-exported-insight "
"entries (id, short_id, name, query_hash, cache_key, query_results, optional query_error)."
),
)
recipient_results = serializers.JSONField(
read_only=True, help_text="Per-destination outcomes; items use status success, failed, or partial."
)
status = serializers.ChoiceField(
choices=DELIVERY_STATUS_CHOICES,
read_only=True,
help_text="Overall run status: starting, completed, failed, or skipped.",
)
error = serializers.JSONField(
allow_null=True, read_only=True, help_text="Top-level failure payload when status is failed, if any."
)
created_at = serializers.DateTimeField(read_only=True, help_text="When the delivery row was created.")
last_updated_at = serializers.DateTimeField(read_only=True, help_text="Last ORM update to this row.")
finished_at = serializers.DateTimeField(
allow_null=True, read_only=True, help_text="When the run finished, if applicable."
)
change_summary = serializers.CharField(
allow_null=True,
read_only=True,
help_text="AI-generated summary included in this delivery, when one was produced.",
)
ai_report = serializers.SerializerMethodField(
help_text="AI-generated report markdown delivered by this run. Null for non-AI deliveries or runs without a persisted report."
)
ai_report_diagnostics = serializers.SerializerMethodField(
help_text="Per-step query diagnostics (generated HogQL + failure type) for this report. Null for non-AI deliveries or runs without persisted diagnostics."
)
ai_report_charts = serializers.SerializerMethodField(
help_text="Charts rendered for this report, in the order they were delivered. Empty when the report had no charts. Null for non-AI deliveries and for deliveries recorded before charts existed."
)
ai_report_prompt = serializers.SerializerMethodField(
help_text="The subscription's prompt as it was when this report was generated. Null for older deliveries and non-AI deliveries."
)
ai_query_plan_status = serializers.SerializerMethodField(
help_text=(
"Query plan state recorded for this delivery: frozen, not_frozen, or planner_updated. "
"Null for older deliveries and non-AI deliveries."
)
)
def _content_snapshot_text(self, delivery: contracts.SubscriptionDeliveryRecord, key: str) -> Optional[str]:
snapshot = delivery.content_snapshot
if not isinstance(snapshot, dict):
return None
value = snapshot.get(key)
return value if isinstance(value, str) and value else None
@extend_schema_field(serializers.CharField(allow_null=True))
def get_ai_report(self, delivery: contracts.SubscriptionDeliveryRecord) -> Optional[str]:
return self._content_snapshot_text(delivery, AI_REPORT_SNAPSHOT_KEY)
@extend_schema_field(serializers.CharField(allow_null=True))
def get_ai_report_prompt(self, delivery: contracts.SubscriptionDeliveryRecord) -> Optional[str]:
return self._content_snapshot_text(delivery, AI_REPORT_PROMPT_SNAPSHOT_KEY)
@extend_schema_field(AIReportQueryDiagnosticSerializer(many=True, allow_null=True))
def get_ai_report_diagnostics(self, delivery: contracts.SubscriptionDeliveryRecord) -> Optional[list[dict]]:
snapshot = delivery.content_snapshot
if not isinstance(snapshot, dict):
return None
diagnostics = snapshot.get(AI_REPORT_DIAGNOSTICS_KEY)
return diagnostics if isinstance(diagnostics, list) else None
@extend_schema_field(AIReportChartSerializer(many=True, allow_null=True))
def get_ai_report_charts(self, delivery: contracts.SubscriptionDeliveryRecord) -> Optional[list[dict]]:
snapshot = delivery.content_snapshot
if not isinstance(snapshot, dict):
return None
charts = snapshot.get(AI_REPORT_CHARTS_KEY)
return charts if isinstance(charts, list) else None
@extend_schema_field(serializers.ChoiceField(choices=AI_QUERY_PLAN_STATUS_CHOICES, allow_null=True))
def get_ai_query_plan_status(self, delivery: contracts.SubscriptionDeliveryRecord) -> Optional[str]:
snapshot = delivery.content_snapshot
if not isinstance(snapshot, dict):
return None
status = snapshot.get(AI_REPORT_QUERY_PLAN_STATUS_KEY)
return status if isinstance(status, str) and status in _AI_QUERY_PLAN_STATUS_VALUES else None
def to_representation(self, instance: contracts.SubscriptionDeliveryRecord) -> dict:
data = super().to_representation(instance)
# The viewset sets this flag when an AI prompt delivery is read by a caller without query
# access; scrub the query-derived report so subscription:read (or a self-granted query:read
# scope) can't read analytics the user isn't allowed to run themselves. ai_report_prompt is
# user-authored and already readable on the subscription, so it is deliberately not scrubbed.
if self.context.get("hide_ai_report"):
data.update(self.AI_REPORT_SCRUBBED)
if isinstance(data.get("error"), dict) and data["error"].get("type") == AI_REPORT_QUERY_FAILURE_TYPE:
data["error"] = self.AI_REPORT_SCRUBBED_ERROR
return data
# The AI report now ships via the typed ai_report / ai_report_diagnostics / ai_report_prompt
# fields, so drop the same keys from content_snapshot to avoid shipping the report twice.
# The non-AI scaffold (insights, dashboard, total_insight_count) stays intact.
snapshot = data.get("content_snapshot")
if isinstance(snapshot, dict) and (
AI_REPORT_SNAPSHOT_KEY in snapshot
or AI_REPORT_PROMPT_SNAPSHOT_KEY in snapshot
or AI_REPORT_DIAGNOSTICS_KEY in snapshot
or AI_REPORT_CHARTS_KEY in snapshot
or AI_REPORT_QUERY_PLAN_STATUS_KEY in snapshot
):
data["content_snapshot"] = {
key: value
for key, value in snapshot.items()
if key
not in (
AI_REPORT_SNAPSHOT_KEY,
AI_REPORT_PROMPT_SNAPSHOT_KEY,
AI_REPORT_DIAGNOSTICS_KEY,
AI_REPORT_CHARTS_KEY,
AI_REPORT_QUERY_PLAN_STATUS_KEY,
)
}
return data
class SubscriptionDeliveryCursorPagination(FacadeCursorPagination):
page_size = 50
ordering = "-created_at"
_PARENT_SUBSCRIPTION_ID_PARAMETER = OpenApiParameter("subscription_id", OpenApiTypes.INT, OpenApiParameter.PATH)
@extend_schema_view(
list=extend_schema(
extensions={"x-product": "subscriptions"},
summary="List subscription deliveries",
description="Paginated delivery history for a subscription. Requires premium subscriptions.",
parameters=[
_PARENT_SUBSCRIPTION_ID_PARAMETER,
OpenApiParameter(
name="status",
type=str,
enum=_DELIVERY_STATUS_VALUES,
location=OpenApiParameter.QUERY,
required=False,
description="Return only deliveries in this run status (starting, completed, failed, or skipped).",
),
],
responses={200: OpenApiResponse(response=SubscriptionDeliverySerializer(many=True))},
),
retrieve=extend_schema(
extensions={"x-product": "subscriptions"},
summary="Retrieve subscription delivery",
description="Fetch one delivery row by id.",
parameters=[
_PARENT_SUBSCRIPTION_ID_PARAMETER,
OpenApiParameter(
"id",
OpenApiTypes.UUID,
OpenApiParameter.PATH,
description="A UUID string identifying this subscription delivery.",
),
],
responses={200: SubscriptionDeliverySerializer},
),
)
@extend_schema(tags=["subscriptions"], extensions={"x-product": "subscriptions"})
class SubscriptionDeliveryViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
scope_object = "subscription"
serializer_class = SubscriptionDeliverySerializer
pagination_class = SubscriptionDeliveryCursorPagination
# subscription is not an access-control resource, and a delivery has no access rules of its own.
records_have_object_access_rules = False
def get_serializer_context(self) -> dict:
context = super().get_serializer_context()
context["hide_ai_report"] = self._should_hide_ai_report()
return context
def _should_hide_ai_report(self) -> bool:
# An AI prompt subscription's delivered report is query-derived, so reading it requires query
# access — mirroring the create/test-delivery gate. Non-AI deliveries are unaffected.
subscription_id = self.kwargs.get("parent_lookup_subscription_id")
if not subscription_id:
return True # nested route always supplies this; fail closed (scrub) if it ever doesn't
if not api.is_ai_prompt_subscription(team_id=self.team_id, subscription_id=subscription_id):
return False
return not self.user_access_control.check_access_level_for_resource("query", "viewer")
def list(self, request: Request, **kwargs: object) -> Response:
status_param = request.query_params.get("status")
if status_param and status_param not in _DELIVERY_STATUS_VALUES:
raise ValidationError(
{"status": [f"Must be one of: {', '.join(sorted(_DELIVERY_STATUS_VALUES))}."]},
)
return facade_cursor_page_response(
self,
lambda page: api.list_subscription_deliveries(
team_id=self.team_id,
subscription_id=self.kwargs.get("parent_lookup_subscription_id"),
status=status_param or None,
viewer=self.user_access_control,
page=page,
filter_by_object_access=not is_service_auth(request),
include_all_if_admin=request.GET.get("admin_include_all") == "true",
),
)
def read_object(self) -> contracts.SubscriptionDeliveryRecord:
try:
return api.get_subscription_delivery(
team_id=self.team_id,
subscription_id=self.kwargs.get("parent_lookup_subscription_id"),
delivery_id=self.kwargs["pk"],
viewer=self.user_access_control,
)
except contracts.MalformedIdError:
raise Http404
except contracts.SubscriptionNotFoundError:
raise Http404("No SubscriptionDelivery matches the given query.")
def retrieve(self, request: Request, **kwargs: object) -> Response:
return Response(self.get_serializer(self.get_object()).data)