: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
"""HTTP layer for the Endpoints product.
The viewset is intentionally thin: authentication/permissions, request parsing,
and response serialization. Business logic lives in ``backend/logic``:
- ``logic.crud``: create/update/destroy orchestration + activity logging
- ``logic.execution``: the /run path (materialized / inline / DuckLake)
- ``logic.materialization``: enable/disable/preview materialization
- ``logic.strategies``: HogQL vs insight query behavior
- ``logic.validation``: request payload validation
"""
import re
import builtins
import dataclasses
from typing import Literal, cast
from uuid import UUID
from django.db.models import Count, F, Prefetch
from django.shortcuts import get_object_or_404
from django_filters.rest_framework import DjangoFilterBackend
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema_view
from pydantic import ValidationError as PydanticValidationError
from rest_framework import serializers, status, viewsets
from rest_framework.exceptions import PermissionDenied, ValidationError
from rest_framework.permissions import IsAuthenticated
from rest_framework.request import Request
from rest_framework.response import Response
from posthog.schema import (
EndpointLastExecutionTimesRequest,
EndpointRequest,
EndpointRunRequest,
QueryStatus,
QueryStatusResponse,
)
from posthog.api.documentation import extend_schema
from posthog.api.log_entries import LogEntryMixin
from posthog.api.mixins import PydanticModelMixin, ValidatedRequest, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.shared import UserBasicSerializer
from posthog.api.tagged_item import TaggedItemViewSetMixin
from posthog.api.utils import action
from posthog.auth import ProjectSecretAPIKeyAuthentication
from posthog.clickhouse.query_tagging import Product
from posthog.exceptions_capture import capture_exception
from posthog.models import TaggedItem, User
from posthog.permissions import (
APIScopePermission,
TeamMemberAccessPermission,
is_authenticated_via_project_secret_api_key,
)
from posthog.schema_migrations.upgrade import upgrade
from products.access_control.backend.facade.user_access_control import access_level_satisfied_for_resource
from products.access_control.backend.presentation.access_control import AccessControlViewSetMixin
from products.data_modeling.backend.facade.api import (
HasDependentsError,
allowed_saved_query_ids,
blocked_lineage_node_id,
describe_dependents,
)
from products.data_modeling.backend.facade.contracts import Dependent
from products.data_modeling.backend.facade.models import DataModelingJob
from products.endpoints.backend.facade.api import (
EndpointCrudService,
EndpointExecutionService,
EndpointMaterializationService,
build_materialization_info,
generate_openapi_spec,
get_last_execution_times,
validate_bucket_overrides,
validate_endpoint_request,
validate_update_request,
)
from products.endpoints.backend.facade.enums import ENDPOINT_NAME_REGEX, ENDPOINTS_LOG_SOURCE
from products.endpoints.backend.facade.models import Endpoint, EndpointVersion
from products.endpoints.backend.presentation.serializers import (
EndpointMaterializationSerializer,
EndpointRequestSerializer,
EndpointResponseSerializer,
EndpointRunResponseSerializer,
EndpointVersionResponseSerializer,
)
from products.endpoints.backend.presentation.throttles import (
EndpointBurstThrottle,
EndpointProjectSecretApiKeyTeamBurstThrottle,
EndpointProjectSecretApiKeyTeamSustainedThrottle,
EndpointSustainedThrottle,
charge_inline_rate,
)
class EndpointDependentsValidationError(serializers.ValidationError):
def __init__(self, detail: str, node_id: str | None = None) -> None:
super().__init__(detail, code="has_dependents")
if node_id:
self.extra = {"node_id": node_id}
class MaterializationPreviewRequestSerializer(serializers.Serializer):
version = serializers.IntegerField(
required=False, help_text="Endpoint version to preview. Defaults to the current version."
)
bucket_overrides = serializers.DictField(
child=serializers.CharField(),
required=False,
allow_null=True,
help_text='Per-column bucket function overrides, e.g. {"timestamp": "hour"}',
)
class MaterializationPreviewRangePairSerializer(serializers.Serializer):
column = serializers.CharField(help_text="Column the query buckets on.")
variables = serializers.ListField(
child=serializers.CharField(),
help_text="Query variables that filter on this column.",
)
bucket_fn = serializers.CharField(help_text="Bucket function applied to the column.")
class MaterializationPreviewAggregateSerializer(serializers.Serializer):
expression = serializers.CharField(help_text="Aggregate expression in the transformed query.")
reaggregate_fn = serializers.CharField(
allow_null=True,
help_text="Function that combines materialized partials again, or null when there is none.",
)
class MaterializationPreviewResponseSerializer(serializers.Serializer):
can_materialize = serializers.BooleanField(help_text="Whether the endpoint query can be materialized.")
reason = serializers.CharField(
allow_null=True,
help_text="Why the query cannot be materialized, or null when it can.",
)
transformed_query = serializers.CharField(
allow_null=True,
help_text="Query rewritten for materialization, when one could be produced.",
)
execution_query = serializers.CharField(
allow_null=True,
help_text="Query that would run against the materialized table.",
)
display_execution_query = serializers.CharField(
allow_null=True,
help_text="Execution query formatted for display.",
)
range_pairs = MaterializationPreviewRangePairSerializer(
many=True,
help_text="Bucketed columns and the variables that filter on them.",
)
aggregates = MaterializationPreviewAggregateSerializer(
many=True,
help_text="Aggregate expressions and how to re-aggregate them.",
)
ENDPOINT_VERSION_PARAMETER = OpenApiParameter(
name="version",
type=OpenApiTypes.INT,
location=OpenApiParameter.QUERY,
required=False,
description="Endpoint version to act on. Defaults to the current version.",
)
@extend_schema_view(
partial_update=extend_schema(
request=EndpointRequestSerializer,
responses={200: EndpointResponseSerializer},
description="Update an existing endpoint.",
),
)
class EndpointViewSet(
TeamAndOrgViewSetMixin,
AccessControlViewSetMixin,
PydanticModelMixin,
TaggedItemViewSetMixin,
LogEntryMixin,
viewsets.ModelViewSet,
):
authentication_classes = [ProjectSecretAPIKeyAuthentication]
psak_allowed_actions = ["run"]
scope_object = "endpoint"
# Read endpoint execution logs from the `log_entries` table keyed by this source.
log_source = ENDPOINTS_LOG_SOURCE
# Special case for query - these are all essentially read actions
scope_object_read_actions = [
"retrieve",
"list",
"run",
"versions",
"openapi_spec",
"materialization_preview",
"materialization_status",
"get_endpoints_last_execution_times",
"logs",
]
scope_object_write_actions: list[str] = [
"create",
"destroy",
"update",
"partial_update",
]
lookup_field = "name"
queryset = Endpoint.objects.all()
filter_backends = [DjangoFilterBackend]
filterset_fields = ["is_active", "created_by"]
def safely_get_queryset(self, queryset):
queryset = queryset.filter(deleted=False)
if self.action == "list":
# Offset pages need a fixed order, or rows can repeat or go missing between pages. The
# partial index on (team, name) for undeleted endpoints serves this order.
queryset = queryset.order_by("name", "id")
return queryset
def get_serializer_class(self):
return serializers.Serializer # We use Pydantic models instead; this fallback satisfies drf-spectacular
def get_throttles(self):
return [
EndpointBurstThrottle(),
EndpointSustainedThrottle(),
EndpointProjectSecretApiKeyTeamBurstThrottle(),
EndpointProjectSecretApiKeyTeamSustainedThrottle(),
]
def dangerously_get_permissions(self):
# `run` is the public-facing execution API. It still requires authentication, the
# `endpoint:read` API scope, and project membership, but intentionally skips
# resource-level access control (AccessControlPermission) — a restrictive resource-level
# default must not break execution for API consumers. Explicit per-endpoint
# (object-level) denials are still enforced in run() via _enforce_object_level_access.
if self.action == "run":
return [permission() for permission in (IsAuthenticated, APIScopePermission, TeamMemberAccessPermission)]
raise NotImplementedError()
# ------------------------------------------------------------------
# Access control helpers
# ------------------------------------------------------------------
def _get_endpoint_with_object_access(self, name: str | None) -> Endpoint:
"""Fetch a team-scoped endpoint by name and enforce object-level access controls.
The custom retrieve/destroy/versions/materialization actions fetch endpoints directly via
get_object_or_404, which bypasses get_object()'s built-in check_object_permissions. Routing
through here restores that check so per-endpoint resource access controls (RBAC) are honored,
not just the resource-level defaults.
"""
endpoint = get_object_or_404(Endpoint, team=self.team, name=name, deleted=False)
self.check_object_permissions(self.request, endpoint)
return endpoint
def _enforce_object_level_access(self, endpoint: Endpoint) -> None:
"""Block execution only when the user is explicitly denied this specific endpoint via an
object-level access control. Unlike check_object_permissions, this ignores resource-level
defaults so a restrictive project default doesn't break the public execution API. Creators
and org admins always pass (specific_access_level_for_object returns the highest level).
"""
# PSAK scopes are project-wide and deliberately bypass object-level access controls.
if is_authenticated_via_project_secret_api_key(self.request):
return
specific_level = self.user_access_control.specific_access_level_for_object(endpoint)
if specific_level is not None and not access_level_satisfied_for_resource("endpoint", specific_level, "viewer"):
raise PermissionDenied("You do not have access to this endpoint.")
# ------------------------------------------------------------------
# Request parsing helpers
# ------------------------------------------------------------------
def _parse_version_param(self, request: Request) -> int | None:
"""Parse version number from request body or query params.
Priority: request.data > query param
Returns int or None. Raises ValidationError if invalid format.
"""
body_version = request.data.get("version")
if body_version is not None:
try:
return int(body_version)
except (ValueError, TypeError):
raise ValidationError({"version": f"Must be an integer, got: {body_version}"})
query_version = request.query_params.get("version")
if query_version is not None:
try:
return int(query_version)
except (ValueError, TypeError):
raise ValidationError({"version": f"Must be an integer, got: {query_version}"})
return None
@staticmethod
def _parse_int_param(
body_value: int | None, query_param: str | None, name: str, min_value: int | None = None
) -> tuple[int | None, Response | None]:
"""Parse an integer from the request body or query params. Returns (value, error_response)."""
value = body_value
if value is None and query_param is not None:
try:
value = int(query_param)
if min_value is not None and value < min_value:
raise ValueError()
except (ValueError, TypeError):
return None, Response(
{"error": f"Invalid {name} parameter: {query_param}"},
status=status.HTTP_400_BAD_REQUEST,
)
elif value is not None and min_value is not None and value < min_value:
return None, Response(
{"error": f"Invalid {name} parameter: {value}"},
status=status.HTTP_400_BAD_REQUEST,
)
return value, None
def _resolve_version_param(self, request: Request, endpoint: Endpoint) -> EndpointVersion | Response:
"""Resolve the ?version=N param to a version, or a 404 Response if it doesn't exist."""
version_number = self._parse_version_param(request)
if version_number is None:
return endpoint.get_version()
try:
return endpoint.get_version(version_number)
except EndpointVersion.DoesNotExist:
return Response({"error": f"Version {version_number} not found"}, status=status.HTTP_404_NOT_FOUND)
# ------------------------------------------------------------------
# Serialization
# ------------------------------------------------------------------
def _get_tag_names(self, endpoint: Endpoint) -> list[str]:
"""Read tag names from the prefetched cache or from the DB if not prefetched."""
if hasattr(endpoint, "prefetched_tags"):
return sorted({ti.tag.name for ti in endpoint.prefetched_tags})
return sorted(endpoint.tagged_items.values_list("tag__name", flat=True))
@staticmethod
def _with_materialization_job_prefetches(queryset):
latest_jobs = DataModelingJob.objects.filter(engine=DataModelingJob.Engine.CLICKHOUSE).order_by("-last_run_at")
latest_completed_jobs = latest_jobs.filter(status=DataModelingJob.Status.COMPLETED)
return queryset.select_related("saved_query", "team").prefetch_related(
EndpointVersion.frequency_nodes_prefetch(),
Prefetch("saved_query__datamodelingjob_set", queryset=latest_jobs[:1], to_attr="prefetched_latest_jobs"),
Prefetch(
"saved_query__datamodelingjob_set",
queryset=latest_completed_jobs[:1],
to_attr="prefetched_latest_completed_jobs",
),
)
@classmethod
def _with_serialization_prefetches(cls, queryset):
"""Tags are prefetched by TaggedItemViewSetMixin.filter_queryset; repeating them here
raises a lookup conflict.
Only the current version is fetched, and the history is counted in the database, so an
endpoint with a long version history costs the same as a fresh one.
"""
current_versions = cls._with_materialization_job_prefetches(
EndpointVersion.objects.filter(version=F("endpoint__current_version"))
)
return (
queryset.select_related("created_by")
.prefetch_related(
Prefetch(
"versions",
queryset=current_versions,
to_attr="prefetched_current_versions",
),
)
.annotate(versions_count=Count("versions", distinct=True))
)
@staticmethod
def _current_version(endpoint: Endpoint) -> EndpointVersion:
"""Read the current version from the prefetch, falling back to a query.
The prefetch is empty if `current_version` ever drifts from the versions actually stored,
so the fallback also covers that.
"""
prefetched = getattr(endpoint, "prefetched_current_versions", None)
if prefetched:
return prefetched[0]
return endpoint.get_version()
@staticmethod
def _versions_count(endpoint: Endpoint) -> int:
annotated = getattr(endpoint, "versions_count", None)
if annotated is not None:
return annotated
return endpoint.versions.count()
def _serialize(
self,
obj: Endpoint | EndpointVersion,
request: Request | None = None,
) -> dict:
"""Serialize an Endpoint or EndpointVersion.
Both return the same base fields. EndpointVersion adds version-specific fields.
"""
if isinstance(obj, EndpointVersion):
endpoint = obj.endpoint
version = obj
else:
endpoint = obj
version = self._current_version(endpoint)
versions_count = (
obj.endpoint_versions_count
if isinstance(obj, EndpointVersion) and hasattr(obj, "endpoint_versions_count")
else self._versions_count(endpoint)
)
url = None
ui_url = None
if request:
url = request.build_absolute_uri(endpoint.endpoint_path)
ui_path = f"/project/{endpoint.team_id}/endpoints/{endpoint.name}"
ui_url = request.build_absolute_uri(ui_path)
result = {
"id": str(endpoint.id),
"name": endpoint.name,
"description": version.description,
"query": version.query,
"is_active": version.is_active if isinstance(obj, EndpointVersion) else endpoint.is_active,
"data_freshness_seconds": version.data_freshness_seconds,
"endpoint_path": endpoint.endpoint_path,
"url": url,
"ui_url": ui_url,
"created_at": endpoint.created_at,
"updated_at": endpoint.updated_at,
"created_by": UserBasicSerializer(endpoint.created_by).data if hasattr(endpoint, "created_by") else None,
"is_materialized": version.is_materialized,
"current_version": endpoint.current_version,
"current_version_id": str(version.id),
"versions_count": versions_count,
"derived_from_insight": endpoint.derived_from_insight,
"last_executed_at": endpoint.last_executed_at.isoformat() if endpoint.last_executed_at else None,
"materialization": build_materialization_info(version),
"bucket_overrides": version.bucket_overrides,
"columns": version.get_columns() if version else [],
"tags": self._get_tag_names(endpoint),
"optional_breakdown_properties": list(version.optional_breakdown_properties or []),
}
if isinstance(obj, EndpointVersion):
result["version"] = version.version
result["version_id"] = str(version.id)
result["endpoint_is_active"] = endpoint.is_active
# Version detail returns the version's own execution time (may be null until it's been run).
result["last_executed_at"] = version.last_executed_at.isoformat() if version.last_executed_at else None
result["version_created_at"] = version.created_at.isoformat()
result["version_updated_at"] = version.updated_at.isoformat() if version.updated_at else None
result["version_created_by"] = UserBasicSerializer(version.created_by).data if version.created_by else None
return result
# ------------------------------------------------------------------
# CRUD actions
# ------------------------------------------------------------------
@extend_schema(
responses={200: EndpointResponseSerializer(many=True)},
description="List all endpoints for the team.",
)
def list(self, request: Request, *args, **kwargs) -> Response:
"""List all endpoints for the team."""
queryset = self._with_serialization_prefetches(self.filter_queryset(self.get_queryset()))
page = self.paginate_queryset(queryset)
if page is not None:
results = [self._serialize(endpoint, request) for endpoint in page]
return self.get_paginated_response(results)
results = [self._serialize(endpoint, request) for endpoint in queryset]
return Response({"results": results})
@extend_schema(
parameters=[ENDPOINT_VERSION_PARAMETER],
responses={200: EndpointVersionResponseSerializer},
description="Retrieve an endpoint, or a specific version via ?version=N.",
)
def retrieve(self, request: Request, name=None, *args, **kwargs) -> Response:
"""Retrieve an endpoint, or a specific endpoint version."""
endpoint = self._get_endpoint_with_object_access(name)
version_number = self._parse_version_param(request)
try:
if version_number is not None:
try:
version = endpoint.get_version(version_number)
return Response(self._serialize(version), status=status.HTTP_200_OK)
except EndpointVersion.DoesNotExist:
return Response(
{"error": f"Version {version_number} not found"},
status=status.HTTP_404_NOT_FOUND,
)
return Response(self._serialize(endpoint, request), status=status.HTTP_200_OK)
except Exception as e:
capture_exception(e, {"endpoint_name": endpoint.name, "team_id": self.team_id})
raise ValidationError("Failed to retrieve endpoint.")
@extend_schema(
request=EndpointRequestSerializer,
responses={201: EndpointResponseSerializer},
description="Create a new endpoint.",
)
def create(self, request: Request, *args, **kwargs) -> Response:
"""Create a new endpoint."""
upgraded_query = upgrade(request.data)
data = self.get_model(upgraded_query, EndpointRequest)
validate_endpoint_request(data, self.team, cast(User, request.user), strict=True)
endpoint = EndpointCrudService(self.team, request).create(data)
return Response(
self._serialize(endpoint, request),
status=status.HTTP_201_CREATED,
)
@extend_schema(
request=EndpointRequestSerializer,
responses={200: EndpointResponseSerializer},
description="Update an existing endpoint. Parameters are optional. Pass version in body or ?version=N query param to target a specific version.",
)
def update(self, request: Request, name: str | None = None, *args, **kwargs) -> Response:
"""Update an existing endpoint.
Supports version from body or query params (body takes precedence).
If version is specified, updates target that specific version.
Otherwise, the current version is used.
"""
# Enforce object-level RBAC: a user with global editor scope can still be restricted
# from a specific endpoint via per-object access controls.
endpoint = self._get_endpoint_with_object_access(name)
upgraded_query = upgrade(request.data)
data = self.get_model(upgraded_query, EndpointRequest)
# Soft-delete via PATCH {deleted: true} — reuses destroy() logic, returns 200 with body for MCP
if data.deleted is True:
self.destroy(request, name=name)
return Response({"success": True}, status=status.HTTP_200_OK)
version_number = self._parse_version_param(request)
validate_update_request(
data, self.team, cast(User, request.user), endpoint=endpoint, version_number=version_number
)
try:
outcome = EndpointCrudService(self.team, request).update(endpoint, data, request.data, version_number)
except HasDependentsError as error:
raise self._dependents_error(endpoint.name, error, action="turn off materialization for")
# When targeting a specific version, return version data; otherwise return endpoint data
if outcome.version_targeted and outcome.target_version is not None:
result = self._serialize(outcome.target_version)
else:
result = self._serialize(outcome.endpoint, request)
if outcome.materialization_error:
result["materialization_error"] = outcome.materialization_error
return Response(result)
def destroy(self, request: Request, name=None, *args, **kwargs) -> Response:
"""Delete an endpoint and clean up materialized query."""
endpoint = self._get_endpoint_with_object_access(name)
try:
EndpointCrudService(self.team, request).destroy(endpoint)
except HasDependentsError as error:
raise self._dependents_error(error.view_name, error)
return Response(status=status.HTTP_204_NO_CONTENT)
def _dependents_error(
self,
subject_name: str,
error: HasDependentsError,
*,
action: Literal["delete", "turn off materialization for"] = "delete",
) -> EndpointDependentsValidationError:
visible = self._visible_dependents(error.dependents)
can_read_lineage = self.user_access_control.check_access_level_for_resource(
"warehouse_view", required_level="viewer"
)
return EndpointDependentsValidationError(
describe_dependents(
subject_name,
visible,
any_hidden=len(visible) < len(error.dependents),
action=action,
),
node_id=blocked_lineage_node_id(visible, error.fallback_node_id) if can_read_lineage else None,
)
def _visible_dependents(self, dependents: tuple[Dependent, ...]) -> builtins.list[Dependent]:
endpoint_dependents = [dependent for dependent in dependents if dependent.kind == "endpoint"]
endpoint_saved_query_ids = [
dependent.saved_query_id for dependent in endpoint_dependents if dependent.saved_query_id is not None
]
endpoint_names = [dependent.name for dependent in endpoint_dependents if dependent.saved_query_id is None]
endpoint_versions = EndpointVersion.objects.filter(
endpoint__team=self.team,
saved_query_id__in=endpoint_saved_query_ids,
).select_related("endpoint")
endpoints = {
endpoint.id: endpoint
for endpoint in [
*(version.endpoint for version in endpoint_versions),
*Endpoint.objects.filter(team=self.team, name__in=endpoint_names, deleted=False),
]
}
self.user_access_control.preload_object_access_controls(list(endpoints.values()))
readable_endpoint_ids = {
str(endpoint.id)
for endpoint in endpoints.values()
if self.user_access_control.check_access_level_for_object(endpoint, "viewer")
}
endpoint_ids_by_saved_query = {
str(version.saved_query_id): str(version.endpoint_id) for version in endpoint_versions
}
endpoint_ids_by_name = {endpoint.name: str(endpoint.id) for endpoint in endpoints.values()}
saved_query_ids = [
UUID(dependent.saved_query_id)
for dependent in dependents
if dependent.kind not in {"endpoint", "metric"} and dependent.saved_query_id is not None
]
readable_saved_query_ids = {
str(saved_query_id)
for saved_query_id in allowed_saved_query_ids(
self.team_id,
self.user_access_control,
ids=saved_query_ids,
)
}
metrics_readable = self.user_access_control.check_access_level_for_resource(
"data_catalog", required_level="viewer"
)
return [
dependent
for dependent in dependents
if (
(
dependent.kind == "endpoint"
and (
endpoint_ids_by_saved_query.get(dependent.saved_query_id or "")
or endpoint_ids_by_name.get(dependent.name)
)
in readable_endpoint_ids
)
or (dependent.kind == "metric" and metrics_readable)
or (
dependent.kind not in {"endpoint", "metric"}
and dependent.saved_query_id in readable_saved_query_ids
)
)
]
# ------------------------------------------------------------------
# Execution
# ------------------------------------------------------------------
@staticmethod
def _parse_run_request(request: Request) -> EndpointRunRequest:
"""Parse the run body into field-level errors instead of pydantic's raw error dump."""
try:
return EndpointRunRequest.model_validate(request.data)
except PydanticValidationError as exc:
field_errors = {
".".join(str(part) for part in error["loc"]) or "body": error["msg"] for error in exc.errors()
}
raise ValidationError(field_errors) from exc
@staticmethod
def _rejection_reason(response: Response) -> str:
data = response.data
if isinstance(data, dict):
return str(data.get("error", data))
return str(data)
@extend_schema(
request=EndpointRunRequest,
responses={200: EndpointRunResponseSerializer},
description="Execute endpoint with optional materialization. Supports version parameter, runs latest version if not set.",
)
@action(methods=["GET", "POST"], detail=True)
def run(self, request: Request, name=None, *args, **kwargs) -> Response:
"""Execute endpoint with optional parameters."""
endpoint = get_object_or_404(Endpoint, team=self.team, name=name, is_active=True, deleted=False)
self._enforce_object_level_access(endpoint)
service = EndpointExecutionService(self.team, request)
try:
data = self._parse_run_request(request)
except ValidationError as exc:
service.log_rejected_run(endpoint, service.format_validation_detail(exc.detail))
raise
version_number, err = self._parse_int_param(data.version, request.query_params.get("version"), "version")
if err:
service.log_rejected_run(endpoint, self._rejection_reason(err))
return err
limit, err = self._parse_int_param(data.limit, request.query_params.get("limit"), "limit", min_value=1)
if err:
service.log_rejected_run(endpoint, self._rejection_reason(err))
return err
offset, err = self._parse_int_param(data.offset, request.query_params.get("offset"), "offset", min_value=0)
if err:
service.log_rejected_run(endpoint, self._rejection_reason(err))
return err
if offset is not None and limit is None:
response = Response(
{"error": "offset requires limit to be set"},
status=status.HTTP_400_BAD_REQUEST,
)
service.log_rejected_run(endpoint, self._rejection_reason(response))
return response
version_obj = None
try:
version_obj = endpoint.get_version(version_number)
except EndpointVersion.DoesNotExist:
if version_number is not None:
response = Response(
{
"error": f"Version {version_number} not found for endpoint '{name}'",
"current_version": endpoint.current_version,
},
status=status.HTTP_404_NOT_FOUND,
)
service.log_rejected_run(endpoint, self._rejection_reason(response))
return response
return service.execute(
endpoint,
data,
version_obj,
limit=limit,
offset=offset,
before_inline_fallback=lambda: charge_inline_rate(request, self),
)
@extend_schema(
description=(
"Get the most recent execution time per endpoint (endpoint-level). "
"Timestamps are recorded by the run path for personal-API-key calls. "
"For per-version usage, query the query_log table directly."
),
request=EndpointLastExecutionTimesRequest,
responses={200: QueryStatusResponse},
)
@action(methods=["POST"], detail=False, url_path="last_execution_times")
def get_endpoints_last_execution_times(self, request: Request, *args, **kwargs) -> Response:
try:
data = EndpointLastExecutionTimesRequest.model_validate(request.data)
names = data.names
if not names:
return Response(
QueryStatusResponse(
query_status=QueryStatus(id="", team_id=self.team.pk, complete=True)
).model_dump(),
status=200,
)
for name in names:
if not isinstance(name, str) or not re.fullmatch(ENDPOINT_NAME_REGEX, name):
raise ValidationError({"names": f"Invalid endpoint name: {name}"})
results = [[name, ts.isoformat()] for name, ts in get_last_execution_times(self.team.pk, names)]
query_status = QueryStatus(id="", team_id=self.team.pk, complete=True, results=results)
return Response(QueryStatusResponse(query_status=query_status).model_dump(), status=200)
except Exception as e:
capture_exception(e, {"product": Product.ENDPOINTS, "team_id": self.team_id})
raise
# ------------------------------------------------------------------
# Versions + materialization
# ------------------------------------------------------------------
@extend_schema(
responses={200: EndpointVersionResponseSerializer(many=True)},
description="List all versions for an endpoint.",
)
@action(methods=["GET"], detail=True)
def versions(self, request: Request, name=None, *args, **kwargs) -> Response:
"""List all versions for an endpoint.
Returns versions in descending order (latest first).
"""
endpoint = self._get_endpoint_with_object_access(name)
versions_qs = (
self._with_materialization_job_prefetches(endpoint.versions.all())
.select_related("endpoint", "endpoint__created_by", "created_by")
.prefetch_related(
Prefetch(
"endpoint__tagged_items",
queryset=TaggedItem.objects.select_related("tag"),
to_attr="prefetched_tags",
)
)
.annotate(endpoint_versions_count=Count("endpoint__versions", distinct=True))
.order_by("-version")
)
page = self.paginate_queryset(versions_qs)
if page is not None:
results = [self._serialize(v) for v in page]
return self.get_paginated_response(results)
results = [self._serialize(v) for v in versions_qs]
return Response({"results": results})
@extend_schema(
parameters=[ENDPOINT_VERSION_PARAMETER],
responses={200: EndpointMaterializationSerializer},
description="Get materialization status for an endpoint. Supports ?version=N query param.",
)
@action(methods=["GET"], detail=True, url_path="materialization_status")
def materialization_status(self, request: Request, name=None, *args, **kwargs) -> Response:
"""Get materialization status for an endpoint without fetching full endpoint data.
Supports ?version=N query param to get status for a specific version.
"""
endpoint = self._get_endpoint_with_object_access(name)
version = self._resolve_version_param(request, endpoint)
if isinstance(version, Response):
return version
return Response(build_materialization_info(version, endpoint_name=endpoint.name))
@validated_request(
MaterializationPreviewRequestSerializer,
responses={200: OpenApiResponse(response=MaterializationPreviewResponseSerializer)},
description="Preview the materialization transform for an endpoint. Shows what the query will look like after materialization, including range pair detection and bucket functions.",
)
@action(methods=["POST"], detail=True, url_path="materialization_preview")
def materialization_preview(self, request: ValidatedRequest, name=None, *args, **kwargs) -> Response:
"""Preview the materialization transform without enabling it.
Returns the transformed query, range pair info, and aggregate re-aggregation info.
"""
endpoint = self._get_endpoint_with_object_access(name)
version_number = request.validated_data.get("version")
if version_number is not None:
try:
version = endpoint.get_version(version_number)
except EndpointVersion.DoesNotExist:
return Response({"error": f"Version {version_number} not found"}, status=status.HTTP_404_NOT_FOUND)
else:
version = endpoint.get_version()
bucket_overrides = request.validated_data.get("bucket_overrides")
if bucket_overrides:
validate_bucket_overrides(bucket_overrides)
service = EndpointMaterializationService(self.team, request)
return Response(dataclasses.asdict(service.preview(endpoint, version, bucket_overrides)))
@extend_schema(
# url_path="openapi.json" would otherwise produce `..._openapi.json_retrieve` —
# the `.` is rejected by lint_spec_consistency_hook + the MCP YAML scaffolder.
operation_id="endpoints_openapi_spec_retrieve",
description="Get OpenAPI 3.0 specification for this endpoint. Use this to generate typed SDK clients.",
parameters=[ENDPOINT_VERSION_PARAMETER],
)
@action(methods=["GET"], detail=True, url_path="openapi.json")
def openapi_spec(self, request: Request, name=None, *args, **kwargs) -> Response:
"""Generate OpenAPI 3.0 specification for this endpoint.
Returns a spec that can be used with tools like openapi-generator,
`@hey-api/openapi-ts`, or any other OpenAPI-compatible SDK generator.
Supports ?version=N query param to generate spec for a specific version.
"""
endpoint = self._get_endpoint_with_object_access(name)
version = None
version_number = self._parse_version_param(request)
if version_number is not None:
try:
version = endpoint.get_version(version_number)
except EndpointVersion.DoesNotExist:
return Response({"error": f"Version {version_number} not found"}, status=status.HTTP_404_NOT_FOUND)
spec = generate_openapi_spec(endpoint, self.team.id, request, version)
return Response(spec, content_type="application/json")
# ------------------------------------------------------------------
# Tags
# ------------------------------------------------------------------
@extend_schema(exclude=True)
@action(methods=["POST"], detail=False)
def bulk_update_tags(self, request: Request, *args, **kwargs) -> Response:
# The inherited TaggedItemViewSetMixin.bulk_update_tags assumes integer PKs (its
# BulkUpdateTagsRequestSerializer validates ids as IntegerField). Endpoint uses
# UUID PKs, so the action is unusable. Return 405 until the mixin gains UUID support.
return Response(
{"detail": "Bulk tag updates are not supported for endpoints."},
status=status.HTTP_405_METHOD_NOT_ALLOWED,
)