: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
"""
Django REST API endpoint for LLM trace and event summarization.
This ViewSet provides AI-powered summarization of LLM traces and events using
line-numbered text representations and LLM calls.
Endpoints:
- POST /api/projects/:id/llm_analytics/summarization/ - Summarize trace or event
- POST /api/projects/:id/llm_analytics/summarization/batch_check/ - Check cached summaries for multiple traces
"""
import time
from datetime import datetime
from typing import TYPE_CHECKING, Any, cast
from django.core.cache import cache
import structlog
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiExample, extend_schema
from rest_framework import exceptions, serializers, status, viewsets
from rest_framework.decorators import action
from rest_framework.request import Request
from rest_framework.response import Response
from posthog.schema import DateRange, IntervalType, TraceQuery
from posthog.hogql import ast
from posthog.hogql.parser import parse_select
from posthog.hogql.query import execute_hogql_query
from posthog.api.monitoring import monitor
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.clickhouse.query_tagging import Feature, Product, tags_context
from posthog.event_usage import report_user_action
from posthog.hogql_queries.ai.ai_table_resolver import AIEventsExpiredError, AIEventsUnavailableError, query_ai_events
from posthog.hogql_queries.ai.trace_query_runner import TraceQueryRunner
from posthog.hogql_queries.ai.utils import (
HEAVY_COLUMN_NAMES,
HEAVY_PROPERTY_NAMES,
merge_heavy_properties,
parse_ai_properties,
)
from posthog.hogql_queries.utils.query_date_range import QueryDateRange
from posthog.permissions import AccessControlPermission
from posthog.rate_limit import (
AIObservabilitySummarizationBurstThrottle,
AIObservabilitySummarizationDailyThrottle,
AIObservabilitySummarizationSustainedThrottle,
)
from products.access_control.backend.facade.api import (
get_restricted_properties_with_group_type_index_for_team,
split_restricted_property_names,
)
from products.ai_observability.backend.api.metrics import llma_track_latency
from products.ai_observability.backend.summarization.budget import (
batch_text_repr_budget,
bounded_text_repr,
text_repr_budget,
)
from products.ai_observability.backend.summarization.llm import summarize
from products.ai_observability.backend.summarization.models import SummarizationMode
from products.ai_observability.backend.summarization.utils import (
get_summarization_lookup_date_range,
get_summary_cache_key,
)
from products.ai_observability.backend.text_repr.formatters import (
FormatterOptions,
format_event_text_repr,
format_trace_text_repr,
llm_trace_to_formatter_format,
)
if TYPE_CHECKING:
from posthog.models import User
logger = structlog.get_logger(__name__)
# Event types the formatters can render on their own, so a single one of them can be summarized by UUID.
SUMMARIZABLE_EVENT_TYPES = ["$ai_generation", "$ai_span", "$ai_embedding", "$ai_evaluation"]
# The frontend matches this code to keep the expected 404 out of error tracking
# (CONTENT_EXPIRED_SELF_HANDLED_BY_LOGIC_PATH in frontend/src/initKea.ts). Keep both in sync.
CONTENT_EXPIRED_ERROR_CODE = "content_expired"
def _compact_cache_key(cache_key: str) -> str:
return f"{cache_key}:compact"
# Request/Response Serializers
class SummarizeRequestSerializer(serializers.Serializer):
summarize_type = serializers.ChoiceField(
choices=["trace", "event"],
required=False,
help_text="Type of entity to summarize. Inferred automatically when using trace_id or generation_id.",
)
mode = serializers.ChoiceField(
choices=[m.value for m in SummarizationMode],
default=SummarizationMode.MINIMAL.value,
help_text="Summary detail level: 'minimal' for 3-5 points, 'detailed' for 5-10 points",
)
data = serializers.JSONField( # type: ignore[assignment]
required=False,
help_text="Data to summarize. For traces: {trace, hierarchy}. For events: {event}. "
"Not required when using trace_id or generation_id.",
)
force_refresh = serializers.BooleanField(
default=False,
required=False,
help_text="Force regenerate summary, bypassing cache",
)
compact_context = serializers.BooleanField(
default=False,
required=False,
help_text="Bound the input to a cost-conscious size instead of the full model context window. "
"Use it when you summarize many traces at once and need only a short result such as the title.",
)
model = serializers.CharField(
default=None,
required=False,
allow_null=True,
allow_blank=True,
help_text="LLM model to use (defaults based on provider)",
)
# ID-based lookup fields (alternative to data)
trace_id = serializers.CharField(
required=False,
help_text="Trace ID to summarize. The backend fetches the trace data automatically. "
"Requires date_from for efficient lookup.",
)
generation_id = serializers.CharField(
required=False,
help_text="Generation event UUID to summarize. The backend fetches the event data automatically. "
"Requires date_from for efficient lookup.",
)
date_from = serializers.CharField(
required=False,
default=None,
allow_null=True,
help_text="Start of date range for ID-based lookup (e.g. '-7d' or '2026-01-01'). Defaults to -30d.",
)
date_to = serializers.CharField(
required=False,
default=None,
allow_null=True,
help_text="End of date range for ID-based lookup. Defaults to now.",
)
def validate(self, attrs: dict) -> dict:
has_data = "data" in attrs and attrs["data"] is not None
has_trace_id = bool(attrs.get("trace_id"))
has_generation_id = bool(attrs.get("generation_id"))
has_id = has_trace_id or has_generation_id
if has_data and has_id:
raise serializers.ValidationError("Provide either 'data' or a trace_id/generation_id, not both.")
if not has_data and not has_id:
raise serializers.ValidationError("Provide either 'data' or a trace_id/generation_id.")
if has_trace_id and has_generation_id:
raise serializers.ValidationError("Provide either trace_id or generation_id, not both.")
# When using IDs, override summarize_type to prevent mismatches
if has_trace_id:
attrs["summarize_type"] = "trace"
elif has_generation_id:
attrs["summarize_type"] = "event"
# summarize_type is required when using data
if has_data and not attrs.get("summarize_type"):
raise serializers.ValidationError("summarize_type is required when using 'data'.")
return attrs
class SummaryBulletSerializer(serializers.Serializer):
text = serializers.CharField()
line_refs = serializers.CharField()
class InterestingNoteSerializer(serializers.Serializer):
text = serializers.CharField()
line_refs = serializers.CharField() # Can be empty string if no line refs
class StructuredSummarySerializer(serializers.Serializer):
title = serializers.CharField(help_text="Concise title (no longer than 10 words) summarizing the trace/event")
flow_diagram = serializers.CharField(help_text="Mermaid flowchart code showing the main flow")
summary_bullets = SummaryBulletSerializer(many=True, help_text="Main summary bullets")
interesting_notes = InterestingNoteSerializer(
many=True, help_text="Interesting notes (0-2 for minimal, more for detailed)"
)
class SummarizeResponseSerializer(serializers.Serializer):
summary = StructuredSummarySerializer(
help_text="Structured AI-generated summary with flow, bullets, and optional notes",
)
text_repr = serializers.CharField(
help_text="Line-numbered text representation that the summary references",
)
metadata = serializers.JSONField(
required=False,
help_text="Metadata about the summarization",
)
class BatchCheckRequestSerializer(serializers.Serializer):
trace_ids = serializers.ListField(
child=serializers.CharField(),
help_text="List of trace IDs to check for cached summaries",
max_length=100,
)
mode = serializers.ChoiceField(
choices=[m.value for m in SummarizationMode],
default=SummarizationMode.MINIMAL.value,
help_text="Summary detail level to check for",
)
model = serializers.CharField(
default=None,
required=False,
allow_null=True,
allow_blank=True,
help_text="LLM model used for cached summaries",
)
class CachedSummarySerializer(serializers.Serializer):
trace_id = serializers.CharField()
title = serializers.CharField()
cached = serializers.BooleanField(default=True)
class BatchCheckResponseSerializer(serializers.Serializer):
summaries = CachedSummarySerializer(many=True)
class AIObservabilitySummarizationViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
"""
ViewSet for LLM trace and event summarization.
Provides AI-powered summarization using line-numbered text representations.
"""
scope_object = "llm_analytics"
permission_classes = [AccessControlPermission]
def get_throttles(self):
"""Apply rate limiting to prevent abuse of summarization endpoint."""
return [
AIObservabilitySummarizationBurstThrottle(),
AIObservabilitySummarizationSustainedThrottle(),
AIObservabilitySummarizationDailyThrottle(),
]
def _validate_feature_access(self, request: Request) -> None:
"""Validate that the user is authenticated and AI data processing is approved."""
if not request.user.is_authenticated:
raise exceptions.NotAuthenticated()
if not self.organization.is_ai_data_processing_approved:
raise exceptions.PermissionDenied(
"AI data processing must be approved by your organization before using summarization"
)
def _get_cache_key(
self,
summarize_type: str,
entity_id: str,
mode: str,
model: str | None = None,
) -> str:
"""Generate cache key for summary results.
Args:
summarize_type: 'trace' or 'event'
entity_id: Unique identifier for the entity being summarized
mode: Summary detail level ('minimal' or 'detailed')
model: LLM model
"""
return get_summary_cache_key(
self.team_id,
summarize_type,
entity_id,
mode,
model,
restricted_properties=get_restricted_properties_with_group_type_index_for_team(
user=cast("User", self.request.user), team_id=self.team_id
),
)
@staticmethod
def _get_cached_summary(cache_key: str, compact_context: bool) -> dict | None:
"""Read a cached summary. A full-context summary also serves a compact request, but not the opposite."""
if compact_context:
compact_result = cache.get(_compact_cache_key(cache_key))
if compact_result is not None:
return compact_result
return cache.get(cache_key)
@staticmethod
def _cache_summary(cache_key: str, result: dict, compact_context: bool) -> None:
if compact_context:
cache.set(_compact_cache_key(cache_key), result, timeout=3600)
return
cache.set(cache_key, result, timeout=3600)
# A compact request reads the compact entry first, so an older one would hide this newer summary.
cache.delete(_compact_cache_key(cache_key))
def _extract_entity_id(self, summarize_type: str, data: dict) -> tuple[str, dict]:
"""Extract entity ID and validated entity data based on summarize type.
Args:
summarize_type: 'trace' or 'event'
data: Request data containing trace/event information
Returns:
Tuple of (entity_id, entity_data) where entity_data is trace or event dict
Raises:
ValidationError: If required fields are missing or invalid
"""
if summarize_type == "trace":
if not data.get("trace") or not isinstance(data.get("hierarchy"), list):
raise exceptions.ValidationError("Trace summarization requires 'trace' and 'hierarchy' fields")
trace = data["trace"]
entity_id = trace.get("properties", {}).get("$ai_trace_id") or trace.get("id")
if not entity_id:
raise exceptions.ValidationError("Trace must have either '$ai_trace_id' or 'id'")
return entity_id, {"trace": trace, "hierarchy": data["hierarchy"]}
elif summarize_type == "event":
if not data.get("event"):
raise exceptions.ValidationError("Event summarization requires 'event' field")
event = data["event"]
entity_id = event.get("id")
if not entity_id:
raise exceptions.ValidationError("Event must have an 'id' field")
return entity_id, {"event": event}
else:
raise exceptions.ValidationError(f"Invalid summarize_type: {summarize_type}")
def _fetch_trace_data(self, trace_id: str, date_from: str | None, date_to: str | None) -> tuple[str, dict]:
"""Fetch trace by ID and return (entity_id, entity_data) for summarization."""
date_range = DateRange(
date_from=date_from or "-30d",
date_to=date_to,
)
runner = TraceQueryRunner(
team=self.team,
user=cast("User", self.request.user),
query=TraceQuery(traceId=trace_id, dateRange=date_range),
)
response = runner.calculate()
if not response.results:
raise exceptions.NotFound(f"Trace '{trace_id}' not found in the given date range.")
trace_obj = response.results[0]
trace_dict, hierarchy = llm_trace_to_formatter_format(trace_obj, nest_children=True)
return trace_id, {"trace": trace_dict, "hierarchy": hierarchy}
def _fetch_generation_data(
self, generation_id: str, date_from: str | None, date_to: str | None
) -> tuple[str, dict]:
"""Fetch a single event by UUID and return (entity_id, entity_data) for summarization.
Covers every event type the trace view offers a summary for, not just generations.
The message content is read separately: ingestion strips the heavy `$ai_*` properties out
of the shared events table and keeps them only in `posthog.ai_events`, so the events row
carries the metadata but none of the conversation.
"""
qdr = QueryDateRange(
DateRange(date_from=date_from or "-30d", date_to=date_to),
self.team,
IntervalType.DAY,
datetime.now(),
)
date_from_expr = ast.Constant(value=qdr.date_from().isoformat())
date_to_expr = ast.Constant(value=qdr.date_to().isoformat())
with tags_context(product=Product.LLM_ANALYTICS, feature=Feature.QUERY, team_id=self.team_id):
result = execute_hogql_query(
query=parse_select(
"""
SELECT uuid, event, timestamp, properties, properties.$ai_trace_id
FROM events
WHERE event IN {summarizable_events}
AND uuid = {generation_uuid}
AND timestamp >= {date_from}
AND timestamp <= {date_to}
LIMIT 1
""",
),
placeholders={
"summarizable_events": ast.Tuple(exprs=[ast.Constant(value=e) for e in SUMMARIZABLE_EVENT_TYPES]),
"generation_uuid": ast.Constant(value=generation_id),
"date_from": date_from_expr,
"date_to": date_to_expr,
},
team=self.team,
user=cast("User", self.request.user),
)
if not result.results:
raise exceptions.NotFound(f"Event '{generation_id}' not found in the given date range.")
uuid_value, event_name, timestamp, properties_json, trace_id = result.results[0]
properties = parse_ai_properties(properties_json)
# Events ingested before the ai_events split still carry their content here, and are old
# enough that ai_events has aged them out, so only look there when it is actually missing.
if not any(properties.get(name) for name in HEAVY_PROPERTY_NAMES):
heavy_columns = self._fetch_heavy_columns(generation_id, str(trace_id or ""), date_from_expr, date_to_expr)
properties = merge_heavy_properties(properties_json, heavy_columns)
event_data = {
"id": str(uuid_value),
"event": event_name,
"timestamp": timestamp.isoformat() if hasattr(timestamp, "isoformat") else str(timestamp),
"properties": properties,
}
return generation_id, {"event": event_data}
def _fetch_heavy_columns(
self, event_uuid: str, trace_id: str, date_from: ast.Constant, date_to: ast.Constant
) -> dict[str, Any]:
"""Read the message content columns for an event whose own properties no longer carry them.
Anchored on `trace_id` because it leads that table's sorting key, per the rationale in
`posthog/hogql_queries/ai/trace_id_resolver.py`.
"""
if not trace_id:
return {}
# nosemgrep: hogql-fstring-audit (only the fixed HEAVY_COLUMN_NAMES constant is interpolated; every user value uses a HogQL placeholder)
query = parse_select(
f"""
SELECT {", ".join(HEAVY_COLUMN_NAMES)}
FROM posthog.ai_events
WHERE trace_id = {{trace_id}}
AND uuid = {{event_uuid}}
AND timestamp >= {{date_from}}
AND timestamp <= {{date_to}}
LIMIT 1
""",
)
placeholders: dict[str, ast.Expr] = {
"trace_id": ast.Constant(value=trace_id),
"event_uuid": ast.Constant(value=event_uuid),
"date_from": date_from,
"date_to": date_to,
}
try:
result = query_ai_events(
query=query,
placeholders=placeholders,
team=self.team,
user=cast("User", self.request.user),
query_type="LLMAnalyticsSummarizationHeavyFetch",
)
except AIEventsExpiredError:
raise exceptions.NotFound(
"The message content for this event is no longer available, so it can't be summarized.",
code=CONTENT_EXPIRED_ERROR_CODE,
) from None
except AIEventsUnavailableError:
return {}
return dict(zip(HEAVY_COLUMN_NAMES, result.results[0]))
def _generate_text_repr(
self, summarize_type: str, entity_data: dict, model: str | None = None, compact_context: bool = False
) -> str:
"""Generate line-numbered text representation for summarization.
Args:
summarize_type: 'trace' or 'event'
entity_data: Dict containing trace/event data
compact_context: Bound the text to the batch ceiling instead of the model window
Returns:
Line-numbered text representation
"""
# Each trace of an agent session can repeat the full conversation, so a fan-out over a session
# at the model window pays for a huge trace on every call.
budget = batch_text_repr_budget(model) if compact_context else text_repr_budget(model)
options: FormatterOptions = {
"include_line_numbers": True,
"truncated": False,
"include_markers": False,
"collapsed": False,
"max_length": budget,
}
if summarize_type == "trace":
text, _ = format_trace_text_repr(
trace=entity_data["trace"],
hierarchy=entity_data["hierarchy"],
options=options,
)
return text
# format_event_text_repr ignores max_length, so the budget has to be applied to its result.
return bounded_text_repr(format_event_text_repr(event=entity_data["event"], options=options), budget)
def _build_summary_response(self, summary, text_repr: str, summarize_type: str) -> dict:
"""Build the API response dict from summary and text representation.
Args:
summary: Pydantic summary model from LLM
text_repr: Line-numbered text representation
summarize_type: 'trace' or 'event'
Returns:
Response dict with summary, text_repr, and metadata
"""
return {
"summary": summary.model_dump(),
"text_repr": text_repr,
"metadata": {
"text_repr_length": len(text_repr),
"summarize_type": summarize_type,
},
}
@extend_schema(
request=SummarizeRequestSerializer,
responses={
200: SummarizeResponseSerializer,
400: OpenApiTypes.OBJECT,
403: OpenApiTypes.OBJECT,
500: OpenApiTypes.OBJECT,
},
examples=[
OpenApiExample(
"Trace Summarization",
description="Summarize a full trace with hierarchy",
value={
"summarize_type": "trace",
"data": {
"trace": {
"id": "trace_123",
"properties": {
"$ai_span_name": "ChatBot Interaction",
},
},
"hierarchy": [
{
"event": {
"id": "gen_1",
"event": "$ai_generation",
"properties": {
"$ai_input": [{"role": "user", "content": "Hello"}],
"$ai_output_choices": [
{"message": {"role": "assistant", "content": "Hi there!"}}
],
},
},
"children": [],
}
],
},
},
request_only=True,
),
OpenApiExample(
"Event Summarization",
description="Summarize a single generation event",
value={
"summarize_type": "event",
"data": {
"event": {
"id": "gen_456",
"event": "$ai_generation",
"properties": {
"$ai_input": [{"role": "user", "content": "Explain Python"}],
"$ai_output_choices": [{"message": {"role": "assistant", "content": "Python is..."}}],
},
}
},
},
request_only=True,
),
OpenApiExample(
"Success Response",
value={
"summary": {
"title": "User greets the assistant",
"flow_diagram": "User → Assistant → Response",
"summary_bullets": [
{"text": "User initiated conversation with a greeting", "line_refs": "L5"},
{"text": "Assistant responded with a friendly message", "line_refs": "L12"},
],
"interesting_notes": [
{"text": "Standard greeting pattern with no errors", "line_refs": ""},
],
},
"text_repr": "L001: user: hi\nL012: assistant: hello",
"metadata": {
"text_repr_length": 450,
"model": "gpt-4.1",
},
},
response_only=True,
status_codes=["200"],
),
],
description="""
Generate an AI-powered summary of an LLM trace or event.
This endpoint analyzes the provided trace/event, generates a line-numbered text
representation, and uses an LLM to create a concise summary with line references.
**Two ways to use this endpoint:**
1. **By ID (recommended):** Pass `trace_id` or `generation_id` with an optional `date_from`/`date_to`.
The backend fetches the data automatically. `summarize_type` is inferred.
2. **By data:** Pass the full trace/event data blob in `data` with `summarize_type`.
This is how the frontend uses it.
**Summary Format:**
- Title (concise, max 10 words)
- Mermaid flow diagram showing the main flow
- 3-10 summary bullets with line references
- "Interesting Notes" section for failures, successes, or unusual patterns
- Line references in [L45] or [L45-52] format pointing to relevant sections
The response includes the structured summary, the text representation, and metadata.
""",
tags=["AI observability"],
)
@llma_track_latency("llma_summarize")
@monitor(feature=None, endpoint="llma_summarize", method="POST")
def create(self, request: Request, **kwargs) -> Response:
"""
Summarize a trace or event.
POST /api/projects/:id/llm_analytics/summarize/
"""
self._validate_feature_access(request)
serializer = SummarizeRequestSerializer(data=request.data)
if not serializer.is_valid():
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
try:
summarize_type = serializer.validated_data["summarize_type"]
mode = serializer.validated_data["mode"]
force_refresh = serializer.validated_data["force_refresh"]
compact_context = serializer.validated_data["compact_context"]
model = serializer.validated_data.get("model")
# Treat empty string as None for model
if model == "":
model = None
trace_id = serializer.validated_data.get("trace_id")
generation_id = serializer.validated_data.get("generation_id")
date_from = serializer.validated_data.get("date_from")
date_to = serializer.validated_data.get("date_to")
entity_data: dict | None = None
if trace_id:
entity_id = trace_id
elif generation_id:
entity_id = generation_id
else:
data = serializer.validated_data["data"]
entity_id, entity_data = self._extract_entity_id(summarize_type, data)
restrictions = get_restricted_properties_with_group_type_index_for_team(
user=cast("User", request.user), team_id=self.team_id
)
# Client payloads may contain values fetched before permissions changed, so refetch to mask them.
# Formatters render only event properties. Other restrictions must not force a lookup
# that could reject a client-only entity without protecting any formatted content.
if split_restricted_property_names(restrictions).event:
if summarize_type == "trace":
trace_id = entity_id
else:
generation_id = entity_id
date_range = get_summarization_lookup_date_range(
entity_data["event"].get("timestamp"), date_from=date_from, date_to=date_to
)
date_from = date_range.date_from
date_to = date_range.date_to
cache_key = self._get_cache_key(summarize_type, entity_id, mode, model)
if not force_refresh:
cached_result = self._get_cached_summary(cache_key, compact_context)
if cached_result is not None:
logger.info(
"Returning cached summary",
summarize_type=summarize_type,
entity_id=entity_id,
mode=mode,
team_id=self.team_id,
)
return Response(cached_result, status=status.HTTP_200_OK)
if trace_id:
_, entity_data = self._fetch_trace_data(trace_id, date_from, date_to)
elif generation_id:
_, entity_data = self._fetch_generation_data(generation_id, date_from, date_to)
if entity_data is None:
raise exceptions.ValidationError("No trace or event data was provided for summarization.")
text_repr = self._generate_text_repr(summarize_type, entity_data, model, compact_context)
start_time = time.time()
user_distinct_id = getattr(request.user, "distinct_id", None)
summary = summarize(
text_repr=text_repr,
team_id=self.team_id,
mode=mode,
model=model,
user_id=user_distinct_id,
)
duration_seconds = time.time() - start_time
result = self._build_summary_response(summary, text_repr, summarize_type)
self._cache_summary(cache_key, result, compact_context)
logger.info(
"Generated and cached new summary",
summarize_type=summarize_type,
entity_id=entity_id,
mode=mode,
team_id=self.team_id,
force_refresh=force_refresh,
)
# Track user action
report_user_action(
self.request.user,
"llma summarization generated",
{
"summarize_type": summarize_type,
"entity_id": entity_id,
"mode": mode,
"text_repr_length": len(text_repr),
"force_refresh": force_refresh,
"compact_context": compact_context,
"duration_seconds": duration_seconds,
},
team=self.team,
request=self.request,
)
return Response(result, status=status.HTTP_200_OK)
except exceptions.APIException:
raise
except Exception as e:
logger.exception(
"Failed to generate summary",
summarize_type=serializer.validated_data.get("summarize_type"),
team_id=self.team_id,
error=str(e),
)
return Response(
{"error": "Failed to generate summary", "detail": "An error occurred while generating the summary"},
status=status.HTTP_500_INTERNAL_SERVER_ERROR,
)
@extend_schema(
request=BatchCheckRequestSerializer,
responses={
200: BatchCheckResponseSerializer,
400: OpenApiTypes.OBJECT,
403: OpenApiTypes.OBJECT,
},
description="""
Check which traces have cached summaries available.
This endpoint allows batch checking of multiple trace IDs to see which ones
have cached summaries. Returns only the traces that have cached summaries
with their titles.
**Use Cases:**
- Load cached summaries on session view load
- Avoid unnecessary LLM calls for already-summarized traces
- Display summary previews without generating new summaries
""",
tags=["AI observability"],
)
@action(detail=False, methods=["post"], url_path="batch_check", required_scopes=["llm_analytics:read"])
@llma_track_latency("llma_summarize_batch_check")
@monitor(feature=None, endpoint="llma_summarize_batch_check", method="POST")
def batch_check(self, request: Request, **kwargs) -> Response:
"""
Check which traces have cached summaries.
POST /api/projects/:id/llm_analytics/summarization/batch_check/
"""
self._validate_feature_access(request)
serializer = BatchCheckRequestSerializer(data=request.data)
if not serializer.is_valid():
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
trace_ids = serializer.validated_data["trace_ids"]
mode = serializer.validated_data["mode"]
model = serializer.validated_data.get("model")
# Treat empty string as None for model
if model == "":
model = None
summaries = []
for trace_id in trace_ids:
cached_result = self._get_cached_summary(
self._get_cache_key("trace", trace_id, mode, model), compact_context=True
)
if cached_result is not None:
summary_data = cached_result.get("summary", {})
title = summary_data.get("title", "Untitled trace")
summaries.append(
{
"trace_id": trace_id,
"title": title,
"cached": True,
}
)
logger.info(
"Batch checked summaries",
trace_count=len(trace_ids),
cached_count=len(summaries),
mode=mode,
team_id=self.team_id,
)
return Response({"summaries": summaries}, status=status.HTTP_200_OK)