Skip to content

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

feat(public-api): optional startTime on GET /observations/{id} (#17193)

Niklas Semmler13edd39b110e
diff --git a/fern/apis/server/definition/legacy/observations-v1.yml b/fern/apis/server/definition/legacy/observations-v1.yml
index eb7221650f..b024d16bf0 100644
--- a/fern/apis/server/definition/legacy/observations-v1.yml
+++ b/fern/apis/server/definition/legacy/observations-v1.yml
@@ -17,6 +17,12 @@ service:
observationId:
type: string
docs: The unique langfuse identifier of an observation, can be an event, span or generation
+ request:
+ name: GetObservationRequest
+ query-parameters:
+ startTime:
+ type: optional<datetime>
+ docs: The start time of the observation (ISO 8601 with offset, e.g. 2024-01-01T00:00:00Z). When provided, the lookup is restricted to the observation's start day, which makes the request substantially faster. Omit it to look up the observation without a time bound.
response: commons.ObservationsViewSingle
getMany:
availability:
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index 819726ea60..c33d68d897 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -3013,6 +3013,18 @@ paths:
required: true
schema:
type: string
+ - name: startTime
+ in: query
+ description: >-
+ The start time of the observation (ISO 8601 with offset, e.g.
+ 2024-01-01T00:00:00Z). When provided, the lookup is restricted to
+ the observation's start day, which makes the request substantially
+ faster. Omit it to look up the observation without a time bound.
+ required: false
+ schema:
+ type: string
+ format: date-time
+ nullable: true
responses:
'200':
description: ''
diff --git a/web/src/__tests__/server/observation-api.servertest.ts b/web/src/__tests__/server/observation-api.servertest.ts
index bddb83bf06..edc2eeb45c 100644
--- a/web/src/__tests__/server/observation-api.servertest.ts
+++ b/web/src/__tests__/server/observation-api.servertest.ts
@@ -7,7 +7,10 @@ import {
createObservationsCh,
createOrgProjectAndApiKey,
} from "@langfuse/shared/src/server";
-import { makeZodVerifiedAPICall } from "@/src/__tests__/test-utils";
+import {
+ makeAPICall,
+ makeZodVerifiedAPICall,
+} from "@/src/__tests__/test-utils";
import {
GetObservationV1Response,
GetObservationsV1Response,
@@ -167,6 +170,70 @@ describe("/api/public/observations API Endpoint", () => {
});
});
+ it("should GET an observation when startTime matches its UTC day", async () => {
+ const observationId = uuidv4();
+ const traceId = uuidv4();
+ const startTime = new Date("2024-03-15T08:30:00.000Z").getTime();
+
+ const observation = createObservationData(useEventsTable, {
+ id: observationId,
+ project_id: projectId,
+ trace_id: traceId,
+ type: "GENERATION",
+ start_time: startTime * timeMultiplier,
+ event_ts: startTime * timeMultiplier,
+ end_time: startTime * timeMultiplier,
+ });
+
+ await insertObservations(useEventsTable, [observation]);
+
+ const getEventRes = await makeZodVerifiedAPICall(
+ GetObservationV1Response,
+ "GET",
+ `/api/public/observations/${observationId}?startTime=2024-03-15T23:59:59.000Z&useEventsTable=${useEventsTable}`,
+ );
+
+ expect(getEventRes.body).toMatchObject({
+ id: observationId,
+ traceId,
+ type: "GENERATION",
+ });
+ });
+
+ it("should 404 when startTime is on a different UTC day", async () => {
+ const observationId = uuidv4();
+ const traceId = uuidv4();
+ const startTime = new Date("2024-03-15T08:30:00.000Z").getTime();
+
+ const observation = createObservationData(useEventsTable, {
+ id: observationId,
+ project_id: projectId,
+ trace_id: traceId,
+ type: "GENERATION",
+ start_time: startTime * timeMultiplier,
+ event_ts: startTime * timeMultiplier,
+ end_time: startTime * timeMultiplier,
+ });
+
+ await insertObservations(useEventsTable, [observation]);
+
+ const res = await makeAPICall(
+ "GET",
+ `/api/public/observations/${observationId}?startTime=2024-03-16T00:00:00.000Z&useEventsTable=${useEventsTable}`,
+ );
+
+ expect(res.status).toBe(404);
+ });
+
+ it("should 400 when startTime lacks a timezone offset", async () => {
+ const res = await makeAPICall(
+ "GET",
+ `/api/public/observations/${uuidv4()}?startTime=2024-03-15T08:30:00&useEventsTable=${useEventsTable}`,
+ );
+
+ expect(res.status).toBe(400);
+ });
+
it.each([
["AGENT", "agent-observation"],
["TOOL", "tool-observation"],
diff --git a/web/src/__tests__/server/unit/get-observation-v1-query.servertest.ts b/web/src/__tests__/server/unit/get-observation-v1-query.servertest.ts
new file mode 100644
index 0000000000..1dbf026b81
--- /dev/null
+++ b/web/src/__tests__/server/unit/get-observation-v1-query.servertest.ts
@@ -0,0 +1,28 @@
+import { GetObservationV1Query } from "@/src/features/public-api/types/observations";
+
+describe("GetObservationV1Query", () => {
+ it("parses without startTime (backwards compatible)", () => {
+ const result = GetObservationV1Query.safeParse({
+ observationId: "obs-1",
+ });
+ expect(result.success).toBe(true);
+ expect(result.data?.startTime).toBeUndefined();
+ });
+
+ it("accepts an ISO datetime with a timezone offset", () => {
+ const result = GetObservationV1Query.safeParse({
+ observationId: "obs-1",
+ startTime: "2024-03-15T08:30:00.000Z",
+ });
+ expect(result.success).toBe(true);
+ expect(result.data?.startTime).toBe("2024-03-15T08:30:00.000Z");
+ });
+
+ it("rejects a datetime without a timezone offset", () => {
+ const result = GetObservationV1Query.safeParse({
+ observationId: "obs-1",
+ startTime: "2024-03-15T08:30:00",
+ });
+ expect(result.success).toBe(false);
+ });
+});
diff --git a/web/src/features/public-api/types/observations.ts b/web/src/features/public-api/types/observations.ts
index 120612bbe9..cbe8083fac 100644
--- a/web/src/features/public-api/types/observations.ts
+++ b/web/src/features/public-api/types/observations.ts
@@ -239,6 +239,10 @@ export const GetObservationsV1Response = z
// GET /observations/{observationId}
export const GetObservationV1Query = z.object({
observationId: z.string(),
+ // Optional timestamp on the observation's start (ISO 8601 with offset).
+ // When provided, it bounds the lookup to that UTC day, making the query
+ // dramatically cheaper. Omit it for the default full lookup.
+ startTime: stringDateTime,
useEventsTable: useEventsTableSchema,
});
// `_deprecation` at the response level, not on the shared `APIObservation`
diff --git a/web/src/pages/api/public/observations/[observationId].ts b/web/src/pages/api/public/observations/[observationId].ts
index f40b4bffb4..3f3213004b 100644
--- a/web/src/pages/api/public/observations/[observationId].ts
+++ b/web/src/pages/api/public/observations/[observationId].ts
@@ -31,17 +31,23 @@ export default withMiddlewares(
rejectInEventsOnlyMode: true,
deprecation: OBSERVATIONS_V1_DEPRECATION,
fn: async ({ query, auth }) => {
+ const startTime = query.startTime
+ ? new Date(query.startTime)
+ : undefined;
+
const clickhouseObservation = query.useEventsTable
? await getObservationByIdFromEventsTable({
id: query.observationId,
projectId: auth.scope.projectId,
fetchWithInputOutput: true,
+ startTime,
})
: // eslint-disable-next-line @typescript-eslint/no-deprecated
await getObservationById({
id: query.observationId,
projectId: auth.scope.projectId,
fetchWithInputOutput: true,
+ startTime,
preferredClickhouseService: "ReadOnly",
});