Aggregate scores across multiple experiments with BTQL

Applies to:

Plan -
Deployment -

Summary

Goal: Aggregate scores across multiple experiments in a single BTQL query. Features: BTQL experiment() multi-ID source, SQL UNPIVOT, GET /v1/experiment API.

Configuration steps

Step 1: Retrieve experiment IDs

Get experiment IDs from the project using the experiments list endpoint:

GET /v1/experiment?project_id=<project_id>&limit=100

Extract the id field from each experiment object in the objects array.

Step 2: Query scores across experiments in a single BTQL call

Pass the collected IDs to experiment(). The source accepts multiple IDs in one call.

SELECT
  experiment_id,
  score,
  avg(value)          AS avg,
  max(created)        AS last_updated
FROM experiment('id1', 'id2', 'id3')
UNPIVOT (value FOR score IN (scores))
GROUP BY experiment_id, score
ORDER BY last_updated DESC

Use standard SQL syntax (no colons on keywords). Braintrust is moving toward SQL style; the colon-prefixed BTQL keyword syntax (FROM:, UNPIVOT:) is not preferred.

Step 3: Use per-experiment summarize as an alternative

If you need the summary shape per experiment rather than raw aggregation:

GET /v1/experiment/{id}/summarize?summarize_scores=true

Loop this call over each experiment ID collected in Step 1.

Limitations

No project-scoped BTQL source (e.g., project_experiments()) exists. Explicit experiment IDs are always required.
No single public endpoint returns the project-level experiment summary shown in the UI. That view is composed from per-experiment summaries internally.

⌘I

​Summary

​Configuration steps

​Step 1: Retrieve experiment IDs

​Step 2: Query scores across experiments in a single BTQL call

​Step 3: Use per-experiment summarize as an alternative

​Limitations

Summary

Configuration steps

Step 1: Retrieve experiment IDs

Step 2: Query scores across experiments in a single BTQL call

Step 3: Use per-experiment summarize as an alternative

Limitations