From 1fe5098f19b08898c126d442a8fb3ddbf1a83852 Mon Sep 17 00:00:00 2001
From: "sentry-junior[bot]"
 <264270552+sentry-junior[bot]@users.noreply.github.com>
Date: Sat, 7 Nov 2026 01:21:03 +0000
Subject: [PATCH] docs(ai-monitoring): Document the sort param on AI
 conversations

The AI conversations list endpoint accepts a sort query parameter,
validated against AI_CONVERSATIONS_FIELDS, with a default of
-conversation.age. The OpenAPI docs didn't list it.

Document it with an enum of the canonical sort fields, each with an
optional - prefix. The legacy spellings the endpoint still accepts while
the frontend and backend deploy independently stay undocumented.

Refs getsentry/toolkit#2073

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
---
 src/sentry/ai_monitoring/constants.py             |  3 +++
 .../endpoints/organization_ai_conversations.py    | 15 ++++++++++++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/sentry/ai_monitoring/constants.py b/src/sentry/ai_monitoring/constants.py
index 98c089d3e61f..24f9afd8ae52 100644
--- a/src/sentry/ai_monitoring/constants.py
+++ b/src/sentry/ai_monitoring/constants.py
@@ -16,6 +16,9 @@
     "conversation.totalTokens": CONVERSATION_AGGREGATE_DEFINITIONS["totalTokens"],
 }
 
+# Documented sort fields, captured before the legacy spellings below are added.
+AI_CONVERSATIONS_SORT_FIELDS = tuple(AI_CONVERSATIONS_FIELDS)
+
 AI_CONVERSATIONS_LEGACY_ALIASES = {
     "conversation.messages": "conversation.llmCalls",
 }
diff --git a/src/sentry/ai_monitoring/endpoints/organization_ai_conversations.py b/src/sentry/ai_monitoring/endpoints/organization_ai_conversations.py
index 82537c0305d1..e16161a34d0a 100644
--- a/src/sentry/ai_monitoring/endpoints/organization_ai_conversations.py
+++ b/src/sentry/ai_monitoring/endpoints/organization_ai_conversations.py
@@ -8,7 +8,7 @@
 from rest_framework.response import Response
 from sentry_sdk import traces
 
-from sentry.ai_monitoring.constants import AI_CONVERSATIONS_FIELDS
+from sentry.ai_monitoring.constants import AI_CONVERSATIONS_FIELDS, AI_CONVERSATIONS_SORT_FIELDS
 from sentry.ai_monitoring.conversation_aggregates import (
     CONVERSATION_AGGREGATE_COLUMNS,
     AIConversationAggregates,
@@ -103,6 +103,18 @@ class AIConversationResponse(AIConversationData):
     ),
 )
 
+AI_CONVERSATIONS_SORT_PARAM = OpenApiParameter(
+    name="sort",
+    location="query",
+    required=False,
+    type=str,
+    enum=[sort for field in AI_CONVERSATIONS_SORT_FIELDS for sort in (field, f"-{field}")],
+    description=(
+        "The field to sort conversations by. Prefix it with `-` to sort in descending order. "
+        "Defaults to `-conversation.age`, most recent first."
+    ),
+)
+
 AI_CONVERSATIONS_PER_PAGE_PARAM = OpenApiParameter(
     name="per_page",
     location="query",
@@ -154,6 +166,7 @@ class OrganizationAIConversationsEndpoint(OrganizationEventsEndpointBase):
             GlobalParams.START,
             GlobalParams.END,
             AI_CONVERSATIONS_QUERY_PARAM,
+            AI_CONVERSATIONS_SORT_PARAM,
             CursorQueryParam,
             AI_CONVERSATIONS_PER_PAGE_PARAM,
         ],