> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggregate scores across multiple experiments with BTQL

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Any
> * Deployment - Any
> *
> * Use case - Retrieving aggregated scores across all experiments in a project using a single BTQL query

## 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.

```sql theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.