Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(public-api): add unstable read-only Topics endpoints (#19104)

Lysander Kiesel14986f6bc53b
diff --git a/fern/apis/server/definition/unstable/topics.yml b/fern/apis/server/definition/unstable/topics.yml
new file mode 100644
index 0000000000..c493843d30
--- /dev/null
+++ b/fern/apis/server/definition/unstable/topics.yml
@@ -0,0 +1,231 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json
+imports:
+ errors: ./errors.yml
+ pagination: ../utils/pagination.yml
+
+service:
+ auth: true
+ base-path: /api/public/unstable
+ endpoints:
+ listFacets:
+ docs: |
+ Unstable: Topics is in closed beta. The shape may change without notice.
+
+ List the project's Topics facets. Only active facets (attached to the
+ project's Topics rule, or all facets if the project has no rule) are
+ returned unless `filter` contains an `active` condition.
+
+ `filter` is a JSON array of filter conditions combined with AND.
+ String matching is case-insensitive. Columns: `id` (stringOptions),
+ `name` (string, stringOptions), `description` (string), `isBuiltIn`
+ (boolean), `active` (boolean).
+ method: GET
+ path: /topic-facets
+ request:
+ name: ListTopicFacetsRequest
+ query-parameters:
+ filter:
+ type: optional<string>
+ docs: JSON array of filter conditions, for example `[{"type":"string","column":"name","operator":"contains","value":"issue"}]`.
+ page:
+ type: optional<integer>
+ docs: 1-based page number. Defaults to `1`.
+ limit:
+ type: optional<integer>
+ docs: Maximum number of items per page. Defaults to `50`, at most `100`.
+ response: TopicFacetList
+ errors:
+ - errors.BadRequestError
+ - errors.UnauthorizedError
+ - errors.AccessDeniedError
+ - errors.NotFoundError
+ - errors.MethodNotAllowedError
+ - errors.TooManyRequestsError
+ - errors.InternalServerError
+ getFacet:
+ docs: |
+ Unstable: Topics is in closed beta. The shape may change without notice.
+
+ Get one Topics facet by id, including inactive facets.
+ method: GET
+ path: /topic-facets/{facetId}
+ path-parameters:
+ facetId: string
+ response: TopicFacet
+ errors:
+ - errors.BadRequestError
+ - errors.UnauthorizedError
+ - errors.AccessDeniedError
+ - errors.NotFoundError
+ - errors.MethodNotAllowedError
+ - errors.TooManyRequestsError
+ - errors.InternalServerError
+ list:
+ docs: |
+ Unstable: Topics is in closed beta. The shape may change without notice.
+
+ List the topics of each active facet's current published map, with
+ the number of traces currently assigned to each topic in the window.
+ Retired topics are not listed. `facets` holds per-facet trace counts
+ by topic status.
+
+ The window applies to the trace start time. It defaults to the last
+ 7 days and can span at most 93 days.
+
+ `filter` is a JSON array of filter conditions combined with AND.
+ String matching is case-insensitive. Columns: `facetId`
+ (stringOptions), `facetName` (string, stringOptions), `id`
+ (stringOptions), `name` (string, stringOptions). Facet conditions also
+ restrict `facets`.
+ method: GET
+ path: /topics
+ request:
+ name: ListTopicsRequest
+ query-parameters:
+ fromTimestamp:
+ type: optional<datetime>
+ docs: Start of the window (trace start time, inclusive). Defaults to 7 days before `toTimestamp`.
+ toTimestamp:
+ type: optional<datetime>
+ docs: End of the window (trace start time, exclusive). Defaults to now.
+ filter:
+ type: optional<string>
+ docs: JSON array of filter conditions, for example `[{"type":"stringOptions","column":"facetName","operator":"any of","value":["Issues"]}]`.
+ orderBy:
+ type: optional<TopicsOrderBy>
+ docs: Defaults to `traceCount.desc`.
+ page:
+ type: optional<integer>
+ docs: 1-based page number. Defaults to `1`.
+ limit:
+ type: optional<integer>
+ docs: Maximum number of items per page. Defaults to `50`, at most `100`.
+ response: TopicList
+ errors:
+ - errors.BadRequestError
+ - errors.UnauthorizedError
+ - errors.AccessDeniedError
+ - errors.NotFoundError
+ - errors.MethodNotAllowedError
+ - errors.TooManyRequestsError
+ - errors.InternalServerError
+ get:
+ docs: |
+ Unstable: Topics is in closed beta. The shape may change without notice.
+
+ Get one topic by its stable id. Topics on the current map are always
+ found. A retired topic is found while traces in the window are still
+ assigned to it, with `inCurrentMap: false`.
+ method: GET
+ path: /topics/{topicId}
+ path-parameters:
+ topicId: string
+ request:
+ name: GetTopicRequest
+ query-parameters:
+ fromTimestamp:
+ type: optional<datetime>
+ docs: Start of the window used for `traceCount`. Defaults to 7 days before `toTimestamp`.
+ toTimestamp:
+ type: optional<datetime>
+ docs: End of the window used for `traceCount`. Defaults to now.
+ response: TopicWithStatus
+ errors:
+ - errors.BadRequestError
+ - errors.UnauthorizedError
+ - errors.AccessDeniedError
+ - errors.NotFoundError
+ - errors.MethodNotAllowedError
+ - errors.TooManyRequestsError
+ - errors.InternalServerError
+
+types:
+ TopicsOrderBy:
+ enum:
+ - value: traceCount.desc
+ name: TraceCountDesc
+ - value: traceCount.asc
+ name: TraceCountAsc
+ - value: name.asc
+ name: NameAsc
+ - value: name.desc
+ name: NameDesc
+ TopicFacetPublishedRun:
+ properties:
+ id: string
+ completedAt: optional<datetime>
+ topicCount: integer
+ TopicFacet:
+ properties:
+ id: string
+ name: string
+ description: string
+ isBuiltIn: boolean
+ active:
+ type: boolean
+ docs: Whether the facet is attached to the project's Topics rule. True for all facets if the project has no rule.
+ version:
+ type: integer
+ docs: Latest facet version.
+ prompt:
+ type: string
+ docs: Prompt of the latest facet version.
+ publishedRun:
+ type: optional<TopicFacetPublishedRun>
+ docs: The run that produced the facet's current map. Null before the first map.
+ TopicFacetList:
+ properties:
+ data: list<TopicFacet>
+ meta: pagination.MetaResponse
+ TopicFacetRef:
+ properties:
+ id: string
+ name: string
+ version: integer
+ TopicWindow:
+ properties:
+ from: datetime
+ to: datetime
+ Topic:
+ properties:
+ id:
+ type: string
+ docs: Stable topic id, kept across map updates.
+ versionId:
+ type: string
+ docs: Id of this topic version.
+ name: string
+ description: string
+ facet: TopicFacetRef
+ runId:
+ type: string
+ docs: The run that produced this topic version.
+ traceCount:
+ type: integer
+ docs: Traces in the window whose current result for the facet is this topic.
+ TopicWithStatus:
+ extends: Topic
+ properties:
+ inCurrentMap:
+ type: boolean
+ docs: False for retired topics that still have assigned traces in the window.
+ window: TopicWindow
+ TopicStatusCounts:
+ docs: Traces in the window by their current result for one facet.
+ properties:
+ assigned: integer
+ outlier: integer
+ awaitingMap: integer
+ notApplicable: integer
+ insufficientInput: integer
+ TopicFacetCounts:
+ properties:
+ facet: TopicFacetRef
+ publishedRunId: optional<string>
+ counts: TopicStatusCounts
+ TopicList:
+ properties:
+ window: TopicWindow
+ data: list<Topic>
+ facets: list<TopicFacetCounts>
+ meta: pagination.MetaResponse
diff --git a/packages/shared/src/topics/index.ts b/packages/shared/src/topics/index.ts
index d5f4b87ab9..fd03cae3bf 100644
--- a/packages/shared/src/topics/index.ts
+++ b/packages/shared/src/topics/index.ts
@@ -13,6 +13,8 @@ export const topicIdSchema = z
.max(128)
.regex(/^[a-zA-Z0-9_-]+$/);
export const topicTraceIdSchema = z.string().min(1).max(1000);
+/** The longest time range any Topics read or update accepts. */
+export const TOPICS_MAX_TIME_RANGE_MS = 93 * 86_400_000;
export const topicTimeRangeSchema = z
.object({ from: z.coerce.date(), to: z.coerce.date() })
.refine(({ from, to }) => from < to, {
@@ -97,10 +99,13 @@ export const topicTraceSelectionCriteriaSchema = topicRuleConfigSchema
message: "Choose an end time after the start time.",
path: ["to"],
})
- .refine(({ from, to }) => to.getTime() - from.getTime() <= 93 * 86400000, {
- message: "Select at most 93 days of traces.",
- path: ["from"],
- });
+ .refine(
+ ({ from, to }) => to.getTime() - from.getTime() <= TOPICS_MAX_TIME_RANGE_MS,
+ {
+ message: "Select at most 93 days of traces.",
+ path: ["from"],
+ },
+ );
export const topicTraceSelectionSnapshotSchema =
topicTraceSelectionCriteriaSchema.safeExtend({
excludedTraceIds: z.array(topicTraceIdSchema).default([]),
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index c6684d1f15..95ee7ef6fb 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -7494,6 +7494,347 @@ paths:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
+ /api/public/unstable/topic-facets:
+ get:
+ description: |-
+ Unstable: Topics is in closed beta. The shape may change without notice.
+
+ List the project's Topics facets. Only active facets (attached to the
+ project's Topics rule, or all facets if the project has no rule) are
+ returned unless `filter` contains an `active` condition.
+
+ `filter` is a JSON array of filter conditions combined with AND.
+ String matching is case-insensitive. Columns: `id` (stringOptions),
+ `name` (string, stringOptions), `description` (string), `isBuiltIn`
+ (boolean), `active` (boolean).
+ operationId: unstable_topics_listFacets
+ tags:
+ - UnstableTopics
+ parameters:
+ - name: filter
+ in: query
+ description: >-
+ JSON array of filter conditions, for example
+ `[{"type":"string","column":"name","operator":"contains","value":"issue"}]`.
+ required: false
+ schema:
+ type: string
+ nullable: true
+ - name: page
+ in: query
+ description: 1-based page number. Defaults to `1`.
+ required: false
+ schema:
+ type: integer
+ nullable: true
+ - name: limit
+ in: query
+ description: Maximum number of items per page. Defaults to `50`, at most `100`.
+ required: false
+ schema:
+ type: integer
+ nullable: true
+ responses:
+ '200':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstableTopicFacetList'
+ '400':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '401':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '403':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '404':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '405':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ security: *ref_0
+ /api/public/unstable/topic-facets/{facetId}:
+ get:
+ description: |-
+ Unstable: Topics is in closed beta. The shape may change without notice.
+
+ Get one Topics facet by id, including inactive facets.
+ operationId: unstable_topics_getFacet
+ tags:
+ - UnstableTopics
+ parameters:
+ - name: facetId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstableTopicFacet'
+ '400':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '401':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '403':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '404':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '405':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ security: *ref_0
+ /api/public/unstable/topics:
+ get:
+ description: |-
+ Unstable: Topics is in closed beta. The shape may change without notice.
+
+ List the topics of each active facet's current published map, with
+ the number of traces currently assigned to each topic in the window.
+ Retired topics are not listed. `facets` holds per-facet trace counts
+ by topic status.
+
+ The window applies to the trace start time. It defaults to the last
+ 7 days and can span at most 93 days.
+
+ `filter` is a JSON array of filter conditions combined with AND.
+ String matching is case-insensitive. Columns: `facetId`
+ (stringOptions), `facetName` (string, stringOptions), `id`
+ (stringOptions), `name` (string, stringOptions). Facet conditions also
+ restrict `facets`.
+ operationId: unstable_topics_list
+ tags:
+ - UnstableTopics
+ parameters:
+ - name: fromTimestamp
+ in: query
+ description: >-
+ Start of the window (trace start time, inclusive). Defaults to 7
+ days before `toTimestamp`.
+ required: false
+ schema:
+ type: string
+ format: date-time
+ nullable: true
+ - name: toTimestamp
+ in: query
+ description: End of the window (trace start time, exclusive). Defaults to now.
+ required: false
+ schema:
+ type: string
+ format: date-time
+ nullable: true
+ - name: filter
+ in: query
+ description: >-
+ JSON array of filter conditions, for example
+ `[{"type":"stringOptions","column":"facetName","operator":"any
+ of","value":["Issues"]}]`.
+ required: false
+ schema:
+ type: string
+ nullable: true
+ - name: orderBy
+ in: query
+ description: Defaults to `traceCount.desc`.
+ required: false
+ schema:
+ $ref: '#/components/schemas/unstableTopicsOrderBy'
+ nullable: true
+ - name: page
+ in: query
+ description: 1-based page number. Defaults to `1`.
+ required: false
+ schema:
+ type: integer
+ nullable: true
+ - name: limit
+ in: query
+ description: Maximum number of items per page. Defaults to `50`, at most `100`.
+ required: false
+ schema:
+ type: integer
+ nullable: true
+ responses:
+ '200':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstableTopicList'
+ '400':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '401':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '403':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '404':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '405':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ security: *ref_0
+ /api/public/unstable/topics/{topicId}:
+ get:
+ description: |-
+ Unstable: Topics is in closed beta. The shape may change without notice.
+
+ Get one topic by its stable id. Topics on the current map are always
+ found. A retired topic is found while traces in the window are still
+ assigned to it, with `inCurrentMap: false`.
+ operationId: unstable_topics_get
+ tags:
+ - UnstableTopics
+ parameters:
+ - name: topicId
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: fromTimestamp
+ in: query
+ description: >-
+ Start of the window used for `traceCount`. Defaults to 7 days before
+ `toTimestamp`.
+ required: false
+ schema:
+ type: string
+ format: date-time
+ nullable: true
+ - name: toTimestamp
+ in: query
+ description: End of the window used for `traceCount`. Defaults to now.
+ required: false
+ schema:
+ type: string
+ format: date-time
+ nullable: true
+ responses:
+ '200':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstableTopicWithStatus'
+ '400':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '401':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '403':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '404':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '405':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ security: *ref_0
components:
schemas:
AnnotationQueueStatus:
@@ -14777,6 +15118,210 @@ components:
required:
- message
- code
+ unstableTopicsOrderBy:
+ title: unstableTopicsOrderBy
+ type: string
+ enum:
+ - traceCount.desc
+ - traceCount.asc
+ - name.asc
+ - name.desc
+ unstableTopicFacetPublishedRun:
+ title: unstableTopicFacetPublishedRun
+ type: object
+ properties:
+ id:
+ type: string
+ completedAt:
+ type: string
+ format: date-time
+ nullable: true
+ topicCount:
+ type: integer
+ required:
+ - id
+ - topicCount
+ unstableTopicFacet:
+ title: unstableTopicFacet
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ description:
+ type: string
+ isBuiltIn:
+ type: boolean
+ active:
+ type: boolean
+ description: >-
+ Whether the facet is attached to the project's Topics rule. True for
+ all facets if the project has no rule.
+ version:
+ type: integer
+ description: Latest facet version.
+ prompt:
+ type: string
+ description: Prompt of the latest facet version.
+ publishedRun:
+ $ref: '#/components/schemas/unstableTopicFacetPublishedRun'
+ nullable: true
+ description: >-
+ The run that produced the facet's current map. Null before the first
+ map.
+ required:
+ - id
+ - name
+ - description
+ - isBuiltIn
+ - active
+ - version
+ - prompt
+ unstableTopicFacetList:
+ title: unstableTopicFacetList
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/unstableTopicFacet'
+ meta:
+ $ref: '#/components/schemas/utilsMetaResponse'
+ required:
+ - data
+ - meta
+ unstableTopicFacetRef:
+ title: unstableTopicFacetRef
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ version:
+ type: integer
+ required:
+ - id
+ - name
+ - version
+ unstableTopicWindow:
+ title: unstableTopicWindow
+ type: object
+ properties:
+ from:
+ type: string
+ format: date-time
+ to:
+ type: string
+ format: date-time
+ required:
+ - from
+ - to
+ unstableTopic:
+ title: unstableTopic
+ type: object
+ properties:
+ id:
+ type: string
+ description: Stable topic id, kept across map updates.
+ versionId:
+ type: string
+ description: Id of this topic version.
+ name:
+ type: string
+ description:
+ type: string
+ facet:
+ $ref: '#/components/schemas/unstableTopicFacetRef'
+ runId:
+ type: string
+ description: The run that produced this topic version.
+ traceCount:
+ type: integer
+ description: >-
+ Traces in the window whose current result for the facet is this
+ topic.
+ required:
+ - id
+ - versionId
+ - name
+ - description
+ - facet
+ - runId
+ - traceCount
+ unstableTopicWithStatus:
+ title: unstableTopicWithStatus
+ type: object
+ properties:
+ inCurrentMap:
+ type: boolean
+ description: >-
+ False for retired topics that still have assigned traces in the
+ window.
+ window:
+ $ref: '#/components/schemas/unstableTopicWindow'
+ required:
+ - inCurrentMap
+ - window
+ allOf:
+ - $ref: '#/components/schemas/unstableTopic'
+ unstableTopicStatusCounts:
+ title: unstableTopicStatusCounts
+ type: object
+ description: Traces in the window by their current result for one facet.
+ properties:
+ assigned:
+ type: integer
+ outlier:
+ type: integer
+ awaitingMap:
+ type: integer
+ notApplicable:
+ type: integer
+ insufficientInput:
+ type: integer
+ required:
+ - assigned
+ - outlier
+ - awaitingMap
+ - notApplicable
+ - insufficientInput
+ unstableTopicFacetCounts:
+ title: unstableTopicFacetCounts
+ type: object
+ properties:
+ facet:
+ $ref: '#/components/schemas/unstableTopicFacetRef'
+ publishedRunId:
+ type: string
+ nullable: true
+ counts:
+ $ref: '#/components/schemas/unstableTopicStatusCounts'
+ required:
+ - facet
+ - counts
+ unstableTopicList:
+ title: unstableTopicList
+ type: object
+ properties:
+ window:
+ $ref: '#/components/schemas/unstableTopicWindow'
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/unstableTopic'
+ facets:
+ type: array
+ items:
+ $ref: '#/components/schemas/unstableTopicFacetCounts'
+ meta:
+ $ref: '#/components/schemas/utilsMetaResponse'
+ required:
+ - window
+ - data
+ - facets
+ - meta
utilsMetaResponse:
title: utilsMetaResponse
type: object
diff --git a/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap b/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
index c12eb89211..fdfffe174d 100644
--- a/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
+++ b/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
@@ -562,6 +562,34 @@ exports[`public-api auth parity > legacy matches the captured baseline except do
"GET unstable/skills/index | org/bearer": 401,
"GET unstable/skills/index | project/basic": 200,
"GET unstable/skills/index | project/bearer": 403,
+ "GET unstable/topic-facets/[facetId] | admin/admin": 401,
+ "GET unstable/topic-facets/[facetId] | agent/basic": 401,
+ "GET unstable/topic-facets/[facetId] | agent/bearer": 401,
+ "GET unstable/topic-facets/[facetId] | org/basic": 403,
+ "GET unstable/topic-facets/[facetId] | org/bearer": 401,
+ "GET unstable/topic-facets/[facetId] | project/basic": 404,
+ "GET unstable/topic-facets/[facetId] | project/bearer": 403,
+ "GET unstable/topic-facets/index | admin/admin": 401,
+ "GET unstable/topic-facets/index | agent/basic": 401,
+ "GET unstable/topic-facets/index | agent/bearer": 401,
+ "GET unstable/topic-facets/index | org/basic": 403,
+ "GET unstable/topic-facets/index | org/bearer": 401,
+ "GET unstable/topic-facets/index | project/basic": 404,
+ "GET unstable/topic-facets/index | project/bearer": 403,
+ "GET unstable/topics/[topicId] | admin/admin": 401,
+ "GET unstable/topics/[topicId] | agent/basic": 401,
+ "GET unstable/topics/[topicId] | agent/bearer": 401,
+ "GET unstable/topics/[topicId] | org/basic": 403,
+ "GET unstable/topics/[topicId] | org/bearer": 401,
+ "GET unstable/topics/[topicId] | project/basic": 404,
+ "GET unstable/topics/[topicId] | project/bearer": 403,
+ "GET unstable/topics/index | admin/admin": 401,
+ "GET unstable/topics/index | agent/basic": 401,
+ "GET unstable/topics/index | agent/bearer": 401,
+ "GET unstable/topics/index | org/basic": 403,
+ "GET unstable/topics/index | org/bearer": 401,
+ "GET unstable/topics/index | project/basic": 404,
+ "GET unstable/topics/index | project/bearer": 403,
"GET v2/datasets/[datasetName]/index | admin/admin": 401,
"GET v2/datasets/[datasetName]/index | agent/basic": 401,
"GET v2/datasets/[datasetName]/index | agent/bearer": 401,
diff --git a/web/src/__tests__/server/public-api-auth-parity.servertest.ts b/web/src/__tests__/server/public-api-auth-parity.servertest.ts
index a93f768d88..257d27c269 100644
--- a/web/src/__tests__/server/public-api-auth-parity.servertest.ts
+++ b/web/src/__tests__/server/public-api-auth-parity.servertest.ts
@@ -139,6 +139,10 @@ const projectRoutes: Route[] = [
methods: ["PATCH", "DELETE"],
},
{ route: "unstable/skills/files/content", methods: ["GET"] },
+ { route: "unstable/topics/index", methods: ["GET"] },
+ { route: "unstable/topics/[topicId]", methods: ["GET"] },
+ { route: "unstable/topic-facets/index", methods: ["GET"] },
+ { route: "unstable/topic-facets/[facetId]", methods: ["GET"] },
];
// Org and misc routes call shadowAuth directly from the handler body.
diff --git a/web/src/__tests__/server/unit/topics.servertest.ts b/web/src/__tests__/server/unit/topics.servertest.ts
index 8ec369bcf2..1ad0b23f34 100644
--- a/web/src/__tests__/server/unit/topics.servertest.ts
+++ b/web/src/__tests__/server/unit/topics.servertest.ts
@@ -1272,12 +1272,16 @@ describe("Topics current results", () => {
expect.arrayContaining([
{
id: "retained",
+ versionId: "retained",
+ runId: "old-map-retained",
name: "Specific refund issues",
description: "Current description",
count: 1,
},
{
id: "retired",
+ versionId: "retired-new",
+ runId: "old-map-retired-new",
name: "Old retired-new",
description: "Historical retired-new",
count: 2,
diff --git a/web/src/__tests__/server/unit/unstable-topics-public-api.servertest.ts b/web/src/__tests__/server/unit/unstable-topics-public-api.servertest.ts
new file mode 100644
index 0000000000..59af821f99
--- /dev/null
+++ b/web/src/__tests__/server/unit/unstable-topics-public-api.servertest.ts
@@ -0,0 +1,377 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { LangfuseNotFoundError } from "@langfuse/shared";
+
+const mocks = vi.hoisted(() => ({
+ isTopicsProjectEnabled: vi.fn(),
+ listTopicFacets: vi.fn(),
+ listTopicRules: vi.fn(),
+ getPublishedTopicRun: vi.fn(),
+ hasStoredTopicSummaries: vi.fn(),
+ readLatestTopicAssignments: vi.fn(),
+ getLatestFacetSummaries: vi.fn(),
+ getTopicRuns: vi.fn(),
+}));
+vi.mock("@langfuse/shared/topics/server", () => mocks);
+
+import {
+ getPublicTopic,
+ getPublicTopicFacet,
+ listPublicTopicFacets,
+ listPublicTopics,
+} from "@/src/features/topics/server/publicApi";
+import { StructuredPublicApiError } from "@/src/features/public-api/types/structuredPublicApiError";
+
+const projectId = "project-a";
+const unitStartTime = "2026-10-19T10:00:00.000Z";
+const window = {
+ fromTimestamp: new Date("2026-10-13T00:00:00Z"),
+ toTimestamp: new Date("2026-10-20T00:00:00Z"),
+};
+
+const facet = (id: string, name: string, isBuiltIn = true) => ({
+ id,
+ projectId,
+ name,
+ description: `${name} facet`,
+ isBuiltIn,
+ versions: [
+ {
+ projectId,
+ facetId: id,
+ version: 2,
+ prompt: `${name} prompt`,
+ createdAt: "2026-10-01T00:00:00.000Z",
+ },
+ ],
+});
+
+const definition = (topicId: string, name: string, runId: string) => ({
+ topicVersionId: `${topicId}-${runId}`,
+ projectId,
+ topicId,
+ createdByRunId: runId,
+ createdAt: "2026-10-18T00:00:00.000Z",
+ tags: [],
+ name,
+ description: `${name} description`,
+ centroid: [],
+ radius: 0,
+ representativeSummaries: [],
+});
+
+const issuesRun = {
+ id: "run-2",
+ projectId,
+ facetId: "issues",
+ facetVersion: 2,
+ status: "completed",
+ createdAt: "2026-10-18T00:00:00.000Z",
+ startedAt: null,
+ finishedAt: "2026-10-18T03:00:00.000Z",
+ config: {},
+ error: null,
+ topics: [
+ definition("timeouts", "Tool call timeouts", "run-2"),
+ // Reused unchanged from the previous run.
+ definition("refunds", "Refund loops", "run-1"),
+ ],
+};
+const oldRun = {
+ ...issuesRun,
+ id: "run-1",
+ topics: [definition("retired", "Retired topic", "run-1")],
+};
+
+const summary = (traceId: string, state: string) => ({
+ projectId,
+ facetId: "issues",
+ facetVersion: 2,
+ traceId,
+ sessionId: null,
+ unitStartTime,
+ processedAt: "2026-10-19T11:00:00.000Z",
+ state,
+ summary: `${traceId} summary`,
+});
+
+const assignment = (
+ traceId: string,
+ topic: { topicId: string; runId: string } | null,
+) => ({
+ projectId,
+ facetId: "issues",
+ facetVersion: 2,
+ traceId,
+ sessionId: null,
+ unitStartTime,
+ summaryProcessedAt: "2026-10-19T11:00:00.000Z",
+ runId: topic?.runId ?? "run-2",
+ topicId: topic?.topicId ?? null,
+ topicVersionId: topic ? `${topic.topicId}-${topic.runId}` : null,
+ assignedAt: "2026-10-19T12:00:00.000Z",
+});
+
+describe("unstable Topics public API", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.isTopicsProjectEnabled.mockReturnValue(true);
+ mocks.listTopicFacets.mockResolvedValue([
+ facet("issues", "Issues"),
+ facet("custom", "Custom Facet", false),
+ ]);
+ mocks.listTopicRules.mockResolvedValue([{ facetIds: ["issues"] }]);
+ mocks.getPublishedTopicRun.mockImplementation(async (_, facetId) =>
+ facetId === "issues" ? issuesRun : null,
+ );
+ mocks.hasStoredTopicSummaries.mockResolvedValue(true);
+ mocks.getLatestFacetSummaries.mockResolvedValue([
+ summary("t1", "complete"),
+ summary("t2", "complete"),
+ summary("t3", "complete"),
+ summary("t4", "complete"),
+ summary("t5", "complete"),
+ summary("t6", "not_applicable"),
+ summary("t7", "insufficient_input"),
+ ]);
+ mocks.readLatestTopicAssignments.mockResolvedValue([
+ assignment("t1", { topicId: "timeouts", runId: "run-2" }),
+ assignment("t2", { topicId: "timeouts", runId: "run-2" }),
+ assignment("t3", { topicId: "retired", runId: "run-1" }),
+ assignment("t4", null),
+ ]);
+ mocks.getTopicRuns.mockResolvedValue([oldRun]);
+ });
+
+ it("returns not found for projects without Topics before reading anything", async () => {
+ mocks.isTopicsProjectEnabled.mockReturnValue(false);
+ const calls = [
+ listPublicTopicFacets({ projectId, page: 1, limit: 50 }),
+ getPublicTopicFacet({ projectId, facetId: "issues" }),
+ listPublicTopics({
+ projectId,
+ orderBy: "traceCount.desc",
+ page: 1,
+ limit: 50,
+ }),
+ getPublicTopic({ projectId, topicId: "timeouts" }),
+ ];
+ for (const call of calls)
+ await expect(call).rejects.toThrow(
+ new LangfuseNotFoundError("Topics is not available for this project."),
+ );
+ expect(mocks.listTopicFacets).not.toHaveBeenCalled();
+ expect(mocks.getLatestFacetSummaries).not.toHaveBeenCalled();
+ });
+
+ it("lists active facets by default and filters case-insensitively", async () => {
+ const active = await listPublicTopicFacets({
+ projectId,
+ page: 1,
+ limit: 50,
+ });
+ expect(active.data).toEqual([
+ {
+ id: "issues",
+ name: "Issues",
+ description: "Issues facet",
+ isBuiltIn: true,
+ active: true,
+ version: 2,
+ prompt: "Issues prompt",
+ publishedRun: {
+ id: "run-2",
+ completedAt: new Date("2026-10-18T03:00:00.000Z"),
+ topicCount: 2,
+ },
+ },
+ ]);
+ expect(active.meta).toEqual({
+ page: 1,
+ limit: 50,
+ totalItems: 1,
+ totalPages: 1,
+ });
+
+ const inactive = await listPublicTopicFacets({
+ projectId,
+ page: 1,
+ limit: 50,
+ filter: [
+ { type: "boolean", column: "active", operator: "=", value: false },
+ {
+ type: "string",
+ column: "name",
+ operator: "contains",
+ value: "FACET",
+ },
+ ],
+ });
+ expect(inactive.data.map(({ id, active }) => ({ id, active }))).toEqual([
+ { id: "custom", active: false },
+ ]);
+
+ await expect(
+ getPublicTopicFacet({ projectId, facetId: "custom" }),
+ ).resolves.toMatchObject({ id: "custom", publishedRun: null });
+ await expect(
+ getPublicTopicFacet({ projectId, facetId: "missing" }),
+ ).rejects.toThrow(LangfuseNotFoundError);
+ });
+
+ it("treats every facet as active when the project has no Topics rule", async () => {
+ mocks.listTopicRules.mockResolvedValue([]);
+ const facets = await listPublicTopicFacets({
+ projectId,
+ page: 1,
+ limit: 50,
+ });
+ expect(facets.data.map(({ id, active }) => [id, active])).toEqual([
+ ["issues", true],
+ ["custom", true],
+ ]);
+ const topics = await listPublicTopics({
+ projectId,
+ ...window,
+ orderBy: "traceCount.desc",
+ page: 1,
+ limit: 50,
+ });
+ expect(topics.facets.map(({ facet }) => facet.id)).toEqual([
+ "issues",
+ "custom",
+ ]);
+ expect(topics.data.map(({ id }) => id)).toEqual(["timeouts", "refunds"]);
+ });
+
+ it("rejects unknown filter columns with the allowed columns", async () => {
+ const error = await listPublicTopicFacets({
+ projectId,
+ page: 1,
+ limit: 50,
+ filter: [
+ { type: "string", column: "constructor", operator: "=", value: "x" },
+ ],
+ }).catch((caught: unknown) => caught);
+ expect(error).toBeInstanceOf(StructuredPublicApiError);
+ expect(error).toMatchObject({
+ httpCode: 400,
+ code: "invalid_query",
+ details: {
+ column: "constructor",
+ allowedValues: ["id", "name", "description", "isBuiltIn", "active"],
+ },
+ });
+ });
+
+ it("lists current-map topics with trace counts and per-status facet counts", async () => {
+ const result = await listPublicTopics({
+ projectId,
+ ...window,
+ orderBy: "traceCount.desc",
+ page: 1,
+ limit: 50,
+ });
+ expect(mocks.getLatestFacetSummaries).toHaveBeenCalledTimes(1);
+ expect(mocks.getLatestFacetSummaries).toHaveBeenCalledWith(
+ projectId,
+ "issues",
+ undefined,
+ { from: window.fromTimestamp, to: window.toTimestamp },
+ undefined,
+ );
+ expect(result.window).toEqual({
+ from: window.fromTimestamp,
+ to: window.toTimestamp,
+ });
+ expect(result.data).toEqual([
+ {
+ id: "timeouts",
+ versionId: "timeouts-run-2",
+ name: "Tool call timeouts",
+ description: "Tool call timeouts description",
+ facet: { id: "issues", name: "Issues", version: 2 },
+ runId: "run-2",
+ traceCount: 2,
+ },
+ expect.objectContaining({ id: "refunds", runId: "run-1", traceCount: 0 }),
+ ]);
+ expect(result.facets).toEqual([
+ {
+ facet: { id: "issues", name: "Issues", version: 2 },
+ publishedRunId: "run-2",
+ counts: {
+ assigned: 3,
+ outlier: 1,
+ awaitingMap: 1,
+ notApplicable: 1,
+ insufficientInput: 1,
+ },
+ },
+ ]);
+
+ const filtered = await listPublicTopics({
+ projectId,
+ ...window,
+ orderBy: "name.asc",
+ page: 1,
+ limit: 50,
+ filter: [
+ {
+ type: "stringOptions",
+ column: "facetName",
+ operator: "none of",
+ value: ["issues"],
+ },
+ ],
+ });
+ expect(filtered.data).toEqual([]);
+ expect(filtered.facets).toEqual([]);
+ expect(mocks.getLatestFacetSummaries).toHaveBeenCalledTimes(1);
+ });
+
+ it("rejects windows longer than 93 days", async () => {
+ await expect(
+ listPublicTopics({
+ projectId,
+ fromTimestamp: new Date("2026-01-01T00:00:00Z"),
+ toTimestamp: new Date("2026-10-01T00:00:00Z"),
+ orderBy: "traceCount.desc",
+ page: 1,
+ limit: 50,
+ }),
+ ).rejects.toMatchObject({ httpCode: 400, code: "invalid_query" });
+ await expect(
+ listPublicTopics({
+ projectId,
+ fromTimestamp: new Date(Date.now() - 100 * 86_400_000),
+ orderBy: "traceCount.desc",
+ page: 1,
+ limit: 50,
+ }),
+ ).rejects.toMatchObject({ httpCode: 400, code: "invalid_query" });
+ expect(mocks.getLatestFacetSummaries).not.toHaveBeenCalled();
+ });
+
+ it("gets current and retired topics by stable id", async () => {
+ await expect(
+ getPublicTopic({ projectId, topicId: "timeouts", ...window }),
+ ).resolves.toMatchObject({
+ id: "timeouts",
+ inCurrentMap: true,
+ traceCount: 2,
+ });
+ await expect(
+ getPublicTopic({ projectId, topicId: "retired", ...window }),
+ ).resolves.toMatchObject({
+ id: "retired",
+ versionId: "retired-run-1",
+ runId: "run-1",
+ name: "Retired topic",
+ inCurrentMap: false,
+ traceCount: 1,
+ });
+ await expect(
+ getPublicTopic({ projectId, topicId: "unknown", ...window }),
+ ).rejects.toThrow(LangfuseNotFoundError);
+ });
+});
diff --git a/web/src/__tests__/server/withMiddlewares.servertest.ts b/web/src/__tests__/server/withMiddlewares.servertest.ts
index 1983ae0dae..7c2435491e 100644
--- a/web/src/__tests__/server/withMiddlewares.servertest.ts
+++ b/web/src/__tests__/server/withMiddlewares.servertest.ts
@@ -109,6 +109,22 @@ describe("clickHouseRouteForRequest", () => {
);
});
+ it("reports static routes as themselves even where a template overlaps them", () => {
+ const apiDir = `${__dirname}/../../pages/api`;
+ const staticPaths = readdirSync(apiDir, { recursive: true })
+ .map(String)
+ .filter((file) => file.endsWith(".ts") && !file.includes("["))
+ .map(
+ (file) => "/api/" + file.replace(/\.ts$/, "").replace(/\/index$/, ""),
+ );
+
+ const misreported = staticPaths.filter(
+ (path) =>
+ clickHouseRouteForRequest(request("GET", path)) !== `GET ${path}`,
+ );
+ expect(misreported).toEqual([]);
+ });
+
it("falls back to UNKNOWN method for missing methods", () => {
expect(
clickHouseRouteForRequest(request(undefined, "/api/public/health")),
diff --git a/web/src/features/public-api/server/clickHouseRequestTags.ts b/web/src/features/public-api/server/clickHouseRequestTags.ts
index 28162627e4..6c0d517e42 100644
--- a/web/src/features/public-api/server/clickHouseRequestTags.ts
+++ b/web/src/features/public-api/server/clickHouseRequestTags.ts
@@ -41,6 +41,8 @@ export const DYNAMIC_API_ROUTE_TEMPLATES = [
"/api/public/skills/[skillName]/versions/[skillVersion]",
"/api/public/unstable/skills/[skillName]",
"/api/public/unstable/skills/[skillName]/versions/[skillVersion]",
+ "/api/public/unstable/topic-facets/[facetId]",
+ "/api/public/unstable/topics/[topicId]",
"/api/public/v2/datasets/[datasetName]",
"/api/public/v2/evaluation-rules/[evaluationRuleId]",
"/api/public/v2/evaluators/[evaluatorId]",
diff --git a/web/src/features/public-api/types/unstable-topics.ts b/web/src/features/public-api/types/unstable-topics.ts
new file mode 100644
index 0000000000..73dfa02086
--- /dev/null
+++ b/web/src/features/public-api/types/unstable-topics.ts
@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { optionalJsonParam, singleFilterList } from "@langfuse/shared";
+
+const pagination = z.object({
+ page: z.coerce.number().int().positive().default(1),
+ limit: z.coerce.number().int().positive().max(100).default(50),
+});
+
+const timeWindow = z.object({
+ fromTimestamp: z.coerce.date().optional(),
+ toTimestamp: z.coerce.date().optional(),
+});
+
+const paginationMeta = z.object({
+ page: z.number(),
+ limit: z.number(),
+ totalItems: z.number(),
+ totalPages: z.number(),
+});
+
+const FacetRefSchema = z
+ .object({ id: z.string(), name: z.string(), version: z.number().int() })
+ .strict();
+
+const WindowSchema = z
+ .object({ from: z.coerce.date(), to: z.coerce.date() })
+ .strict();
+
+const TopicFacetSchema = z
+ .object({
+ id: z.string(),
+ name: z.string(),
+ description: z.string(),
+ isBuiltIn: z.boolean(),
+ active: z.boolean(),
+ version: z.number().int(),
+ prompt: z.string(),
+ publishedRun: z
+ .object({
+ id: z.string(),
+ completedAt: z.coerce.date().nullable(),
+ topicCount: z.number().int(),
+ })
+ .strict()
+ .nullable(),
+ })
+ .strict();
+
+const TopicSchema = z
+ .object({
+ id: z.string(),
+ versionId: z.string(),
+ name: z.string(),
+ description: z.string(),
+ facet: FacetRefSchema,
+ runId: z.string(),
+ traceCount: z.number().int(),
+ })
+ .strict();
+
+const TopicStatusCountsSchema = z
+ .object({
+ assigned: z.number().int(),
+ outlier: z.number().int(),
+ awaitingMap: z.number().int(),
+ notApplicable: z.number().int(),
+ insufficientInput: z.number().int(),
+ })
+ .strict();
+
+export const GetUnstableTopicFacetsQuery = pagination.extend({
+ filter: optionalJsonParam(singleFilterList, "filter"),
+});
+export const GetUnstableTopicFacetsResponse = z
+ .object({ data: z.array(TopicFacetSchema), meta: paginationMeta })
+ .strict();
+
+export const TopicFacetIdQuery = z.object({ facetId: z.string() });
+/** @alias */
+export const GetUnstableTopicFacetResponse = TopicFacetSchema;
+
+const TOPICS_ORDER_BY = [
+ "traceCount.desc",
+ "traceCount.asc",
+ "name.asc",
+ "name.desc",
+] as const;
+
+export const GetUnstableTopicsQuery = pagination
+ .extend(timeWindow.shape)
+ .extend({
+ filter: optionalJsonParam(singleFilterList, "filter"),
+ orderBy: z.enum(TOPICS_ORDER_BY).default("traceCount.desc"),
+ });
+export const GetUnstableTopicsResponse = z
+ .object({
+ window: WindowSchema,
+ data: z.array(TopicSchema),
+ facets: z.array(
+ z
+ .object({
+ facet: FacetRefSchema,
+ publishedRunId: z.string().nullable(),
+ counts: TopicStatusCountsSchema,
+ })
+ .strict(),
+ ),
+ meta: paginationMeta,
+ })
+ .strict();
+
+export const GetUnstableTopicQuery = timeWindow.extend({
+ topicId: z.string(),
+});
+export const GetUnstableTopicResponse = TopicSchema.extend({
+ inCurrentMap: z.boolean(),
+ window: WindowSchema,
+}).strict();
diff --git a/web/src/features/topics/CurrentTopicsView.stories.tsx b/web/src/features/topics/CurrentTopicsView.stories.tsx
index 446e60180f..0173f4228a 100644
--- a/web/src/features/topics/CurrentTopicsView.stories.tsx
+++ b/web/src/features/topics/CurrentTopicsView.stories.tsx
@@ -12,6 +12,8 @@ import {
const topic = {
id: "billing",
+ versionId: "billing-v1",
+ runId: "run",
name: "Billing questions",
description: "Invoice support",
count: 60,
diff --git a/web/src/features/topics/TopicGridView.stories.tsx b/web/src/features/topics/TopicGridView.stories.tsx
index d5a197b775..193d65c049 100644
--- a/web/src/features/topics/TopicGridView.stories.tsx
+++ b/web/src/features/topics/TopicGridView.stories.tsx
@@ -21,7 +21,7 @@ const topics = [
count: 0,
},
{ id: "howto", name: "How-to and onboarding", description: "", count: 0 },
-];
+].map((topic) => ({ ...topic, versionId: `${topic.id}-v1`, runId: "run" }));
const clusters: { topic: number | null; x: number; y: number; n: number }[] = [
{ topic: 0, x: -6, y: -4, n: 70 },
{ topic: 1, x: 5, y: -5, n: 55 },
diff --git a/web/src/features/topics/TopicTreemapView.stories.tsx b/web/src/features/topics/TopicTreemapView.stories.tsx
index 190a25bb6b..ae37182dd8 100644
--- a/web/src/features/topics/TopicTreemapView.stories.tsx
+++ b/web/src/features/topics/TopicTreemapView.stories.tsx
@@ -23,6 +23,8 @@ const names = [
];
const topics = names.map((name, index) => ({
id: `topic-${index}`,
+ versionId: `topic-${index}-v1`,
+ runId: "run",
name,
description: "",
count: counts[index],
@@ -95,7 +97,13 @@ const issueTopics = [
{ name: "Run stopped before delivering final report", count: 18 },
{ name: "Run halted before delivering requested report", count: 18 },
{ name: "Partial answers without follow-up", count: 16 },
-].map((topic, index) => ({ ...topic, id: `issue-${index}`, description: "" }));
+].map((topic, index) => ({
+ ...topic,
+ id: `issue-${index}`,
+ versionId: `issue-${index}-v1`,
+ runId: "run",
+ description: "",
+}));
export const LongNamesOnShortTiles = meta.story({
name: "Long names on short tiles",
diff --git a/web/src/features/topics/TopicTreemapView.tsx b/web/src/features/topics/TopicTreemapView.tsx
index 182b252e6a..89a1007daf 100644
--- a/web/src/features/topics/TopicTreemapView.tsx
+++ b/web/src/features/topics/TopicTreemapView.tsx
@@ -63,6 +63,8 @@ export function TopicTreemapView({
...facet.topics,
{
id: UNASSIGNED_ID,
+ versionId: "",
+ runId: "",
name: "Unassigned",
description: "",
count: unassignedCount,
diff --git a/web/src/features/topics/server/currentResults.ts b/web/src/features/topics/server/currentResults.ts
index 1df0247459..4d576c1530 100644
--- a/web/src/features/topics/server/currentResults.ts
+++ b/web/src/features/topics/server/currentResults.ts
@@ -48,9 +48,11 @@ function resolveTopicResult(
export async function currentTopicResults(
projectId: string,
timeRange: TopicTimeRange,
- traceIds?: string[],
+ { facetIds, traceIds }: { facetIds?: string[]; traceIds?: string[] } = {},
) {
- const facets = await listTopicFacets(projectId);
+ const facets = (await listTopicFacets(projectId)).filter(
+ (facet) => !facetIds || facetIds.includes(facet.id),
+ );
const hasStoredSummaries =
facets.length > 0 && (await hasStoredTopicSummaries(projectId));
if (!hasStoredSummaries) return { hasStoredSummaries, facets: [] };
@@ -164,6 +166,12 @@ export async function currentTopicResults(
topicByVersion.get(topic.assignment.topicVersionId ?? "");
return {
id,
+ versionId:
+ definition?.topicVersionId ??
+ topic.assignment.topicVersionId ??
+ "",
+ runId:
+ definition?.createdByRunId ?? topic.assignment.runId ?? "",
name: definition?.name ?? "Unavailable topic",
description: definition?.description ?? "",
count: topic.count,
@@ -175,6 +183,8 @@ export async function currentTopicResults(
runId: run.id,
topics: run.topics.map((topic) => ({
id: topic.topicId,
+ versionId: topic.topicVersionId,
+ runId: topic.createdByRunId,
name: topic.name,
description: topic.description,
})),
@@ -199,9 +209,9 @@ export async function traceFacetResults(
to: new Date(timestamp.getTime() + slackMs),
});
if (!unitTimeRange) return [];
- const { facets } = await currentTopicResults(projectId, unitTimeRange, [
- traceId,
- ]);
+ const { facets } = await currentTopicResults(projectId, unitTimeRange, {
+ traceIds: [traceId],
+ });
return facets.map((facet) => {
const row = facet.rows.find((item) => item.traceId === traceId);
return {
diff --git a/web/src/features/topics/server/publicApi.ts b/web/src/features/topics/server/publicApi.ts
new file mode 100644
index 0000000000..57d38c8c45
--- /dev/null
+++ b/web/src/features/topics/server/publicApi.ts
@@ -0,0 +1,351 @@
+import { LangfuseNotFoundError, type FilterState } from "@langfuse/shared";
+import { InMemoryFilterService } from "@langfuse/shared/src/server";
+import {
+ TOPICS_MAX_TIME_RANGE_MS,
+ type TopicFacet,
+ type TopicRun,
+ type TopicTimeRange,
+} from "@langfuse/shared/topics";
+import {
+ getPublishedTopicRun,
+ isTopicsProjectEnabled,
+ listTopicFacets,
+ listTopicRules,
+} from "@langfuse/shared/topics/server";
+import { createStructuredPublicApiError } from "@/src/features/public-api/types/structuredPublicApiError";
+import { currentTopicResults } from "./currentResults";
+
+const DEFAULT_WINDOW_MS = 7 * 86_400_000;
+
+type FilterType = FilterState[number]["type"];
+type FilterColumns<T> = Record<
+ string,
+ { types: readonly FilterType[]; value: (row: T) => unknown }
+>;
+
+/**
+ * Public read access uses the project gate only: API keys carry no user, so
+ * the UI's per-user feature preview cannot apply.
+ */
+function assertTopicsApiAvailable(projectId: string) {
+ if (!isTopicsProjectEnabled(projectId))
+ throw new LangfuseNotFoundError(
+ "Topics is not available for this project.",
+ );
+}
+
+function invalidFilter(message: string, column: string, allowed: string[]) {
+ return createStructuredPublicApiError({
+ httpCode: 400,
+ code: "invalid_query",
+ message,
+ details: { column, allowedValues: allowed },
+ });
+}
+
+function lower(value: unknown): unknown {
+ if (typeof value === "string") return value.toLowerCase();
+ if (Array.isArray(value)) return value.map(lower);
+ return value;
+}
+
+/** String matching on Topics routes is case-insensitive. */
+function applyFilter<T>(
+ rows: T[],
+ filter: FilterState | undefined,
+ columns: FilterColumns<T>,
+): T[] {
+ if (!filter || filter.length === 0) return rows;
+ const names = Object.keys(columns);
+ for (const condition of filter) {
+ const column = Object.hasOwn(columns, condition.column)
+ ? columns[condition.column]
+ : undefined;
+ if (!column)
+ throw invalidFilter(
+ `Unknown filter column "${condition.column}".`,
+ condition.column,
+ names,
+ );
+ if (!column.types.includes(condition.type))
+ throw invalidFilter(
+ `Filter column "${condition.column}" does not support type "${condition.type}".`,
+ condition.column,
+ [...column.types],
+ );
+ }
+ const conditions = filter.map(
+ (condition) =>
+ ({
+ ...condition,
+ value: lower(condition.value),
+ }) as FilterState[number],
+ );
+ return rows.filter((row) =>
+ InMemoryFilterService.evaluateFilter(row, conditions, (data, name) =>
+ lower(columns[name].value(data)),
+ ),
+ );
+}
+
+function paginate<T>(rows: T[], page: number, limit: number) {
+ return {
+ data: rows.slice((page - 1) * limit, page * limit),
+ meta: {
+ page,
+ limit,
+ totalItems: rows.length,
+ totalPages: Math.ceil(rows.length / limit),
+ },
+ };
+}
+
+function resolveWindow(from?: Date, to?: Date): TopicTimeRange {
+ const end = to ?? new Date();
+ const start = from ?? new Date(end.getTime() - DEFAULT_WINDOW_MS);
+ if (
+ start >= end ||
+ end.getTime() - start.getTime() > TOPICS_MAX_TIME_RANGE_MS
+ )
+ throw createStructuredPublicApiError({
+ httpCode: 400,
+ code: "invalid_query",
+ message:
+ "fromTimestamp must be before toTimestamp, and the window can span at most 93 days.",
+ });
+ return { from: start, to: end };
+}
+
+// Matches currentTopicResults: the latest rule's facets, or all facets without a rule (manual runs).
+async function isFacetActive(projectId: string) {
+ const [rule] = await listTopicRules(projectId);
+ return (facetId: string) => !rule || rule.facetIds.includes(facetId);
+}
+
+function publicFacet(facet: TopicFacet, active: boolean, run: TopicRun | null) {
+ const version = facet.versions[0];
+ return {
+ id: facet.id,
+ name: facet.name,
+ description: facet.description,
+ isBuiltIn: facet.isBuiltIn,
+ active,
+ version: version?.version ?? 0,
+ prompt: version?.prompt ?? "",
+ publishedRun: run
+ ? {
+ id: run.id,
+ completedAt: run.finishedAt ? new Date(run.finishedAt) : null,
+ topicCount: run.topics.length,
+ }
+ : null,
+ };
+}
+
+type PublicFacet = ReturnType<typeof publicFacet>;
+
+const facetColumns: FilterColumns<PublicFacet> = {
+ id: { types: ["stringOptions"], value: (row) => row.id },
+ name: { types: ["string", "stringOptions"], value: (row) => row.name },
+ description: { types: ["string"], value: (row) => row.description },
+ isBuiltIn: { types: ["boolean"], value: (row) => row.isBuiltIn },
+ active: { types: ["boolean"], value: (row) => row.active },
+};
+
+const hasActiveCondition = (filter: FilterState | undefined) =>
+ filter?.some((condition) => condition.column === "active") ?? false;
+
+async function loadPublicFacets(projectId: string) {
+ const [facets, isActive] = await Promise.all([
+ listTopicFacets(projectId),
+ isFacetActive(projectId),
+ ]);
+ return Promise.all(
+ facets.map(async (facet) =>
+ publicFacet(
+ facet,
+ isActive(facet.id),
+ await getPublishedTopicRun(projectId, facet.id),
+ ),
+ ),
+ );
+}
+
+/** Lists facets; only active facets unless the filter names `active`. */
+export async function listPublicTopicFacets(params: {
+ projectId: string;
+ filter?: FilterState;
+ page: number;
+ limit: number;
+}) {
+ assertTopicsApiAvailable(params.projectId);
+ const facets = applyFilter(
+ await loadPublicFacets(params.projectId),
+ hasActiveCondition(params.filter)
+ ? params.filter
+ : [
+ ...(params.filter ?? []),
+ { type: "boolean", column: "active", operator: "=", value: true },
+ ],
+ facetColumns,
+ );
+ return paginate(facets, params.page, params.limit);
+}
+
+export async function getPublicTopicFacet(params: {
+ projectId: string;
+ facetId: string;
+}) {
+ assertTopicsApiAvailable(params.projectId);
+ const facet = (await loadPublicFacets(params.projectId)).find(
+ ({ id }) => id === params.facetId,
+ );
+ if (!facet) throw new LangfuseNotFoundError("Facet not found.");
+ return facet;
+}
+
+const facetSummaryColumns: FilterColumns<{
+ facet: { id: string; name: string };
+}> = {
+ facetId: { types: ["stringOptions"], value: (row) => row.facet.id },
+ facetName: {
+ types: ["string", "stringOptions"],
+ value: (row) => row.facet.name,
+ },
+};
+
+async function loadPublicTopics(
+ projectId: string,
+ window: TopicTimeRange,
+ facetFilter?: FilterState,
+) {
+ const [facets, isActive] = await Promise.all([
+ listTopicFacets(projectId),
+ isFacetActive(projectId),
+ ]);
+ const facetIds = applyFilter(
+ facets
+ .filter(({ id }) => isActive(id))
+ .map(({ id, name }) => ({ facet: { id, name } })),
+ facetFilter,
+ facetSummaryColumns,
+ ).map(({ facet }) => facet.id);
+ const results = await currentTopicResults(projectId, window, { facetIds });
+ return results.facets.map((facet) => {
+ const ref = {
+ id: facet.facetId,
+ name: facet.name,
+ version: facet.facetVersion ?? 0,
+ };
+ const traceCounts = new Map(facet.topics.map((topic) => [topic.id, topic]));
+ const current = (facet.map?.topics ?? []).map((topic) => ({
+ id: topic.id,
+ versionId: topic.versionId,
+ name: topic.name,
+ description: topic.description,
+ facet: ref,
+ runId: topic.runId,
+ traceCount: traceCounts.get(topic.id)?.count ?? 0,
+ }));
+ const currentIds = new Set(current.map(({ id }) => id));
+ const retired = facet.topics
+ .filter((topic) => !currentIds.has(topic.id))
+ .map((topic) => ({
+ id: topic.id,
+ versionId: topic.versionId,
+ name: topic.name,
+ description: topic.description,
+ facet: ref,
+ runId: topic.runId,
+ traceCount: topic.count,
+ }));
+ const count = (outcome: string) =>
+ facet.rows.filter((row) => row.outcome === outcome).length;
+ return {
+ summary: {
+ facet: ref,
+ publishedRunId: facet.map?.runId ?? null,
+ counts: {
+ assigned: count("assigned"),
+ outlier: count("outlier"),
+ awaitingMap: count("awaiting_map"),
+ notApplicable: count("not_applicable"),
+ insufficientInput: count("insufficient_input"),
+ },
+ },
+ current,
+ retired,
+ };
+ });
+}
+
+type PublicTopic = Awaited<
+ ReturnType<typeof loadPublicTopics>
+>[number]["current"][number];
+
+const topicColumns: FilterColumns<PublicTopic> = {
+ ...facetSummaryColumns,
+ id: { types: ["stringOptions"], value: (row) => row.id },
+ name: { types: ["string", "stringOptions"], value: (row) => row.name },
+};
+
+const topicOrder = {
+ "traceCount.desc": (a: PublicTopic, b: PublicTopic) =>
+ b.traceCount - a.traceCount || a.name.localeCompare(b.name),
+ "traceCount.asc": (a: PublicTopic, b: PublicTopic) =>
+ a.traceCount - b.traceCount || a.name.localeCompare(b.name),
+ "name.asc": (a: PublicTopic, b: PublicTopic) => a.name.localeCompare(b.name),
+ "name.desc": (a: PublicTopic, b: PublicTopic) => b.name.localeCompare(a.name),
+};
+
+/** Lists the topics of each active facet's current map; retired topics are not listed. */
+export async function listPublicTopics(params: {
+ projectId: string;
+ fromTimestamp?: Date;
+ toTimestamp?: Date;
+ filter?: FilterState;
+ orderBy: keyof typeof topicOrder;
+ page: number;
+ limit: number;
+}) {
+ assertTopicsApiAvailable(params.projectId);
+ const window = resolveWindow(params.fromTimestamp, params.toTimestamp);
+ const facets = await loadPublicTopics(
+ params.projectId,
+ window,
+ params.filter?.filter(({ column }) =>
+ Object.hasOwn(facetSummaryColumns, column),
+ ),
+ );
+ const topics = applyFilter(
+ facets.flatMap(({ current }) => current),
+ params.filter,
+ topicColumns,
+ ).sort(topicOrder[params.orderBy]);
+ return {
+ window,
+ facets: facets.map(({ summary }) => summary),
+ ...paginate(topics, params.page, params.limit),
+ };
+}
+
+/**
+ * Resolves a topic of an active facet's current map, or a retired topic that
+ * still has current traces in the window.
+ */
+export async function getPublicTopic(params: {
+ projectId: string;
+ topicId: string;
+ fromTimestamp?: Date;
+ toTimestamp?: Date;
+}) {
+ assertTopicsApiAvailable(params.projectId);
+ const window = resolveWindow(params.fromTimestamp, params.toTimestamp);
+ for (const facet of await loadPublicTopics(params.projectId, window)) {
+ const current = facet.current.find(({ id }) => id === params.topicId);
+ if (current) return { ...current, inCurrentMap: true, window };
+ const retired = facet.retired.find(({ id }) => id === params.topicId);
+ if (retired) return { ...retired, inCurrentMap: false, window };
+ }
+ throw new LangfuseNotFoundError("Topic not found.");
+}
diff --git a/web/src/features/topics/server/topicsRouter.ts b/web/src/features/topics/server/topicsRouter.ts
index a0ace71aee..e36e73afe9 100644
--- a/web/src/features/topics/server/topicsRouter.ts
+++ b/web/src/features/topics/server/topicsRouter.ts
@@ -15,6 +15,7 @@ import {
topicRuleConfigSchema,
topicTimeRangeSchema,
topicsAutomaticProcessingSchema,
+ TOPICS_MAX_TIME_RANGE_MS,
topicsModelSettingsSchema,
topicsSetupSchema,
type TopicTimeRange,
@@ -75,7 +76,7 @@ const SETUP_TRACE_SPAN_MARGIN_MS = 5 * 60_000;
const executionInput = projectInput.extend({ executionId: topicIdSchema });
const resultInput = projectInput.extend({
timeRange: topicTimeRangeSchema.refine(
- ({ from, to }) => to.getTime() - from.getTime() <= 93 * 86_400_000,
+ ({ from, to }) => to.getTime() - from.getTime() <= TOPICS_MAX_TIME_RANGE_MS,
"Select a time range of at most 93 days.",
),
});
diff --git a/web/src/features/topics/server/traceSelection.ts b/web/src/features/topics/server/traceSelection.ts
index d8b1f746a0..496a13e788 100644
--- a/web/src/features/topics/server/traceSelection.ts
+++ b/web/src/features/topics/server/traceSelection.ts
@@ -6,6 +6,7 @@ import {
topicIdSchema,
topicTraceSelectionCriteriaSchema,
topicTraceSelectionSnapshotSchema,
+ TOPICS_MAX_TIME_RANGE_MS,
} from "@langfuse/shared/topics";
import type { PrismaClient } from "@langfuse/shared/src/db";
import { selectTopicTraceRows } from "@langfuse/shared/topics/server";
@@ -43,7 +44,7 @@ export const topicTriggerInputSchema = z
(input) =>
input.operation !== "update" ||
input.timeRange.to.getTime() - input.timeRange.from.getTime() <=
- 93 * 86_400_000,
+ TOPICS_MAX_TIME_RANGE_MS,
"Select a time range of at most 93 days.",
);
diff --git a/web/src/pages/api/public/unstable/topic-facets/[facetId].ts b/web/src/pages/api/public/unstable/topic-facets/[facetId].ts
new file mode 100644
index 0000000000..4f240832e2
--- /dev/null
+++ b/web/src/pages/api/public/unstable/topic-facets/[facetId].ts
@@ -0,0 +1,20 @@
+import {
+ createUnstablePublicApiRoute,
+ withUnstablePublicApiMiddlewares,
+} from "@/src/features/public-api/server/unstable-public-api-route";
+import {
+ GetUnstableTopicFacetResponse,
+ TopicFacetIdQuery,
+} from "@/src/features/public-api/types/unstable-topics";
+import { getPublicTopicFacet } from "@/src/features/topics/server/publicApi";
+
+export default withUnstablePublicApiMiddlewares({
+ GET: createUnstablePublicApiRoute({
+ name: "Get Unstable Topic Facet",
+ action: "topics:read",
+ querySchema: TopicFacetIdQuery,
+ responseSchema: GetUnstableTopicFacetResponse,
+ fn: ({ query, auth }) =>
+ getPublicTopicFacet({ projectId: auth.scope.projectId, ...query }),
+ }),
+});
diff --git a/web/src/pages/api/public/unstable/topic-facets/index.ts b/web/src/pages/api/public/unstable/topic-facets/index.ts
new file mode 100644
index 0000000000..eeeeaabd27
--- /dev/null
+++ b/web/src/pages/api/public/unstable/topic-facets/index.ts
@@ -0,0 +1,20 @@
+import {
+ createUnstablePublicApiRoute,
+ withUnstablePublicApiMiddlewares,
+} from "@/src/features/public-api/server/unstable-public-api-route";
+import {
+ GetUnstableTopicFacetsQuery,
+ GetUnstableTopicFacetsResponse,
+} from "@/src/features/public-api/types/unstable-topics";
+import { listPublicTopicFacets } from "@/src/features/topics/server/publicApi";
+
+export default withUnstablePublicApiMiddlewares({
+ GET: createUnstablePublicApiRoute({
+ name: "List Unstable Topic Facets",
+ action: "topics:read",
+ querySchema: GetUnstableTopicFacetsQuery,
+ responseSchema: GetUnstableTopicFacetsResponse,
+ fn: ({ query, auth }) =>
+ listPublicTopicFacets({ projectId: auth.scope.projectId, ...query }),
+ }),
+});
diff --git a/web/src/pages/api/public/unstable/topics/[topicId].ts b/web/src/pages/api/public/unstable/topics/[topicId].ts
new file mode 100644
index 0000000000..edb96cdebb
--- /dev/null
+++ b/web/src/pages/api/public/unstable/topics/[topicId].ts
@@ -0,0 +1,20 @@
+import {
+ createUnstablePublicApiRoute,
+ withUnstablePublicApiMiddlewares,
+} from "@/src/features/public-api/server/unstable-public-api-route";
+import {
+ GetUnstableTopicQuery,
+ GetUnstableTopicResponse,
+} from "@/src/features/public-api/types/unstable-topics";
+import { getPublicTopic } from "@/src/features/topics/server/publicApi";
+
+export default withUnstablePublicApiMiddlewares({
+ GET: createUnstablePublicApiRoute({
+ name: "Get Unstable Topic",
+ action: "topics:read",
+ querySchema: GetUnstableTopicQuery,
+ responseSchema: GetUnstableTopicResponse,
+ fn: ({ query, auth }) =>
+ getPublicTopic({ projectId: auth.scope.projectId, ...query }),
+ }),
+});
diff --git a/web/src/pages/api/public/unstable/topics/index.ts b/web/src/pages/api/public/unstable/topics/index.ts
new file mode 100644
index 0000000000..3a2d0ca5cc
--- /dev/null
+++ b/web/src/pages/api/public/unstable/topics/index.ts
@@ -0,0 +1,20 @@
+import {
+ createUnstablePublicApiRoute,
+ withUnstablePublicApiMiddlewares,
+} from "@/src/features/public-api/server/unstable-public-api-route";
+import {
+ GetUnstableTopicsQuery,
+ GetUnstableTopicsResponse,
+} from "@/src/features/public-api/types/unstable-topics";
+import { listPublicTopics } from "@/src/features/topics/server/publicApi";
+
+export default withUnstablePublicApiMiddlewares({
+ GET: createUnstablePublicApiRoute({
+ name: "List Unstable Topics",
+ action: "topics:read",
+ querySchema: GetUnstableTopicsQuery,
+ responseSchema: GetUnstableTopicsResponse,
+ fn: ({ query, auth }) =>
+ listPublicTopics({ projectId: auth.scope.projectId, ...query }),
+ }),
+});