diff --git a/src/pages/docs/api/eval-tasks/eval-task-aggregations.mdx b/src/pages/docs/api/eval-tasks/eval-task-aggregations.mdx
index 31cbb9de..9ed98b6e 100644
--- a/src/pages/docs/api/eval-tasks/eval-task-aggregations.mdx
+++ b/src/pages/docs/api/eval-tasks/eval-task-aggregations.mdx
@@ -10,7 +10,9 @@ description: "Aggregate eval-task results as per-eval rollups, per-span pivots,
parameters={[
{"name": "eval_task_id", "in": "query", "required": true, "description": "UUID of the eval task to aggregate.", "type": "string"},
{"name": "eval_aggregation", "in": "query", "required": false, "description": "When true, returns the per-eval rollup keyed by eval name.", "type": "boolean"},
- {"name": "span_aggregation", "in": "query", "required": false, "description": "When true, returns the per-span pivot keyed by span ID.", "type": "boolean"}
+ {"name": "span_aggregation", "in": "query", "required": false, "description": "When true, returns the per-span pivot keyed by span ID.", "type": "boolean"},
+ {"name": "start_date", "in": "query", "required": false, "description": "ISO-8601 lower bound on span creation time. Only spans created at or after this instant are aggregated.", "type": "string"},
+ {"name": "end_date", "in": "query", "required": false, "description": "ISO-8601 upper bound on span creation time. Only spans created at or before this instant are aggregated.", "type": "string"}
]}
responseExample={{
eval_task_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
@@ -68,6 +70,12 @@ description: "Aggregate eval-task results as per-eval rollups, per-span pivots,
When `true`, the response includes the `span_aggregation` object — one entry per span the task evaluated, keyed by `span_id`, with the raw value of every eval that touched it. Defaults to `false`. At least one of `eval_aggregation` or `span_aggregation` must be `true`.
+
+ Inclusive lower bound on the **span's `created_at`** — only eval runs whose linked span was created at or after this instant are aggregated. When omitted, no lower bound is applied.
+
+
+ Inclusive upper bound on the **span's `created_at`** — only eval runs whose linked span was created at or before this instant are aggregated. When omitted, no upper bound is applied.
+
@@ -109,7 +117,9 @@ description: "Aggregate eval-task results as per-eval rollups, per-span pivots,
Soft-deleted eval runs are skipped in both aggregations so the rollups reflect the user's current view of the data.
- `span_aggregation` only includes span-target eval runs — session- and trace-target eval runs (where there is no underlying span) are not included.
+ Both `eval_aggregation` and `span_aggregation` only include span-linked eval runs — session-target eval runs (where there is no underlying span) are excluded from both rollups, regardless of whether a date range is supplied.
+
+ `start_date` and `end_date` filter on the **span's creation time** (`observation_span.created_at`), not on when the eval ran. The aggregation results therefore reflect only those spans that were created in the supplied window — eval runs against spans created outside the window are dropped from both rollups. When neither parameter is supplied, every span linked to the eval task is included.