Run an Experiment Over a Time Window with the REST APIBeta

Beta

This is coming — this page describes a feature that's still being rolled out and may not be available to you yet.

To measure your live traffic without picking sessions one by one, run the experiment on every session in a time window, for example the last seven days.

---

About This Task

A window contains every session of the pipeline whose last activity falls between from and to. You can narrow it with the same filters the session list uses:

Field	Description
from	Required. Start of the window, inclusive. Must include a timezone.
to	Required. End of the window, inclusive. Must include a timezone, be later than from, and not be in the future.
origin	Optional. Only sessions from this origin.
deployment_id	Optional. Only sessions served by this service.
pipeline_version_id	Optional. Only sessions served by this pipeline version.
revision_id	Optional. Only sessions served by this service revision.

The window is always absolute. If your app offers presets such as Last 7 days, convert them to exact from and to times before you send the request.

Prerequisites

• You have an experiment with the metrics you want to run. To create one, see Run an Experiment.
• You need an API key. For details, see Generate API Keys.
• You need the workspace ID, the pipeline ID, and the experiment ID. For the workspace and pipeline IDs, see Workspace ID and Pipeline ID.

Preview the Window

Before you start a run, check how many sessions the window holds. Send the window to the preview endpoint. Replace <WORKSPACE_ID>, <PIPELINE_ID>, and <EXPERIMENT_ID> with your IDs, and <YOUR_API_KEY> with your Haystack Platform API key:

curl --request POST \
     --url https://api.cloud.deepset.ai/api/v2/workspaces/<WORKSPACE_ID>/evaluation/pipelines/<PIPELINE_ID>/metric-groups/<EXPERIMENT_ID>/scoring-runs/preview \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-10-08T00:00:00Z",
  "origin": null
}
'

The response contains:

• sessions: The number of sessions in the window.
• more_than: If true, the window holds more sessions than the ceiling allows, and a run over this window is refused. Narrow the window or add a filter.
• evaluators: The number of metrics in the experiment.
• cells: The number of sessions multiplied by the number of metrics. This is how many results the run produces.
• ceiling: The most sessions (sessions) and results (cells) a window run can have.

The preview count is an estimate. Sessions that arrive before you start the run can change it.

Start the Run

To start the run, send the window in the window field. Set exactly one of session_ids and window. reuse is RERUN_ALL by default, which measures every session in the window again. Set it to REUSE_SUCCEEDED to measure only sessions that don't have a result yet.

curl --request POST \
     --url https://api.cloud.deepset.ai/api/v2/workspaces/<WORKSPACE_ID>/evaluation/pipelines/<PIPELINE_ID>/metric-groups/<EXPERIMENT_ID>/scoring-runs \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "window": {
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-10-08T00:00:00Z"
  },
  "reuse": "REUSE_SUCCEEDED"
}
'

The run measures the sessions in the window when the API receives the request. Traffic that arrives later isn't included.

The experiment keeps the run in its history. When it finishes, read its results as described in Read the Results.

Window runs have these rules:

• A window run is always a sample of your traffic, so you can't set selection to HAND_PICKED.
• You can't use focus with a window, because the sessions don't exist until the API resolves them.
• The run keeps its window and the number of sessions it was launched with (resolved_sessions). Both appear when you read the run.

Window Run Limits

A window run can measure up to 500 sessions and produce up to 1,500 results. These limits are separate from the limits for hand-picked sessions. A large window run can take a while to finish, because it shares the evaluation queue with other runs. For how the queue works, see Runs Waiting for Capacity and Transient Failures.

The API returns a 422 error in these cases:

• The window has no sessions.
• The window is over the limits. The error detail contains a message, the count of sessions, and the ceiling, in the same shape as the preview response. Narrow the window or add a filter, and try again.

Related Information

• Run an Experiment
• Evaluation Experiments
• Generate API Keys