Skip to content

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

docs(public-api): document fromStartTime as required on experiments endpoints (#17603)

Niklas Semmlerbe747a7d2507
diff --git a/fern/apis/server/definition/experiments.yml b/fern/apis/server/definition/experiments.yml
index 48a968b016..55c44c132c 100644
--- a/fern/apis/server/definition/experiments.yml
+++ b/fern/apis/server/definition/experiments.yml
@@ -32,7 +32,11 @@ service:
docs: Versioned base64url cursor from the previous response page.
fromStartTime:
type: datetime
- docs: Retrieve only experiments on or after this datetime.
+ docs: |
+ Required. Retrieve only experiments with events on or after this
+ datetime. A lower bound is required so the query stays fast on
+ large projects; pair it with `toStartTime` to select a specific
+ window.
toStartTime:
type: optional<datetime>
docs: Retrieve only experiments before this datetime.
@@ -80,7 +84,11 @@ service:
docs: Versioned base64url cursor from the previous response page.
fromStartTime:
type: datetime
- docs: Retrieve only experiment items started on or after this datetime.
+ docs: |
+ Required. Retrieve only experiment items started on or after this
+ datetime. A lower bound is required so the query stays fast on
+ large projects; pair it with `toStartTime` to select a specific
+ window.
toStartTime:
type: optional<datetime>
docs: Retrieve only experiment items started before this datetime.
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index 812d7cd65e..b20e583b79 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -2479,7 +2479,11 @@ paths:
nullable: true
- name: fromStartTime
in: query
- description: Retrieve only experiments on or after this datetime.
+ description: |-
+ Required. Retrieve only experiments with events on or after this
+ datetime. A lower bound is required so the query stays fast on
+ large projects; pair it with `toStartTime` to select a specific
+ window.
required: true
schema:
type: string
@@ -2604,7 +2608,11 @@ paths:
nullable: true
- name: fromStartTime
in: query
- description: Retrieve only experiment items started on or after this datetime.
+ description: |-
+ Required. Retrieve only experiment items started on or after this
+ datetime. A lower bound is required so the query stays fast on
+ large projects; pair it with `toStartTime` to select a specific
+ window.
required: true
schema:
type: string
diff --git a/web/src/features/public-api/types/experiments.ts b/web/src/features/public-api/types/experiments.ts
index e9a8419e28..be44207564 100644
--- a/web/src/features/public-api/types/experiments.ts
+++ b/web/src/features/public-api/types/experiments.ts
@@ -87,6 +87,18 @@ const experimentScoreLimitZod = z.preprocess(
z.coerce.number().int().gte(1).lte(50).default(50),
);
+// Required on the experiments endpoints: bounds the events-table scan on
+// start_time (the partition and primary-key column). Keep it required unless a
+// different scan guard is added. The custom error explains the requirement
+// instead of surfacing a bare format error when the parameter is omitted.
+const requiredFromStartTime = z.iso.datetime({
+ offset: true,
+ error: (issue) =>
+ issue.input === undefined
+ ? "fromStartTime is required. It bounds the query to a time window; pass an ISO 8601 datetime with offset (e.g. 2024-01-01T00:00:00Z)."
+ : "fromStartTime must be an ISO 8601 datetime with offset (e.g. 2024-01-01T00:00:00Z).",
+});
+
const experimentFieldsZod = commaSeparatedEnumArray(EXPERIMENT_FIELD_GROUPS, [
"core",
]).describe(
@@ -120,7 +132,7 @@ export const GetExperimentsV1ParsedQuery = z.object({
limit: publicApiPaginationLimitZod,
scoreLimit: experimentScoreLimitZod,
cursor: EncodedExperimentCursorV1.optional(),
- fromStartTime: z.iso.datetime({ offset: true }),
+ fromStartTime: requiredFromStartTime,
toStartTime: z.iso.datetime({ offset: true }).optional(),
id: optionalStringArrayZod,
name: optionalStringArrayZod,
@@ -134,7 +146,7 @@ export const GetExperimentsV1Query = z
limit: publicApiPaginationLimitZod,
scoreLimit: experimentScoreLimitZod,
cursor: EncodedExperimentsCursorString.optional(),
- fromStartTime: z.iso.datetime({ offset: true }),
+ fromStartTime: requiredFromStartTime,
toStartTime: z.iso.datetime({ offset: true }).optional(),
id: optionalCommaSeparatedStringArray,
name: optionalCommaSeparatedStringArray,
@@ -152,7 +164,7 @@ export const GetExperimentItemsV1ParsedQueryBase = z.object({
limit: publicApiPaginationLimitZod,
scoreLimit: experimentScoreLimitZod,
cursor: EncodedExperimentCursorV1.optional(),
- fromStartTime: z.iso.datetime({ offset: true }),
+ fromStartTime: requiredFromStartTime,
toStartTime: z.iso.datetime({ offset: true }).optional(),
experimentId: optionalStringArrayZod,
experimentName: optionalStringArrayZod,
@@ -171,7 +183,7 @@ export const GetExperimentItemsV1Query = z
limit: publicApiPaginationLimitZod,
scoreLimit: experimentScoreLimitZod,
cursor: EncodedExperimentsCursorString.optional(),
- fromStartTime: z.iso.datetime({ offset: true }),
+ fromStartTime: requiredFromStartTime,
toStartTime: z.iso.datetime({ offset: true }).optional(),
experimentId: optionalCommaSeparatedStringArray,
experimentName: optionalCommaSeparatedStringArray,