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

# Include scorer explanations in S3 exports

> Include scorer explanations in S3 exports by switching to span exports or using a custom SQL query.

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Enterprise
> * Deployment - Braintrust-hosted or self-hosted AWS
> * Data plane - Rewind requires v2.1+ with cloud storage export enabled for self-hosted deployments
> * Use case - How to export scorer explanations/rationales to S3: when to use Logs (spans) vs Custom SQL, sample SQL to select output.metadata.rationale, IAM trust-policy wildcard guidance, Rewind/backfill behavior, and downstream implications

## Summary

Use Logs (spans) or a Custom SQL export to include scorer explanations in S3.

## What is happening

Trace-level exports write one summary row per trace. Scorer explanations live on individual scorer spans at `output.metadata.rationale`. A Logs (traces) export does not include that scorer metadata.

## Fix or suggestion

### Option 1: Switch the automation to Logs (spans)

1. Edit the export automation in the UI.
2. Change the data type to Logs (spans).
3. Save the automation.

Your chosen file format and S3 destination remain the same. Expect more rows and higher downstream processing costs. Update downstream mappings to handle multiple span rows per trace.

### Option 2: Use a Custom SQL export (select scorer spans)

1. Edit the export automation and choose Custom SQL.

2. Use a query that reads spans and selects the scorer fields. Replace the placeholder `'<project_id>'` with your project ID.

   ```sql theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   SELECT
     created,
     id,
     span_id,
     root_span_id,
     output.name AS scorer_name,
     output.score AS score,
     output.metadata.rationale AS explanation,
     output.metadata.reason AS reason,
     output.metadata AS scorer_metadata,
     error
   FROM project_logs('<project_id>', shape => 'spans')
   WHERE span_attributes.purpose = 'scorer'
     AND span_attributes.type = 'score'
   ```

   The query already includes the full scorer metadata to help locate rationales stored under another key.

3. Click **Update automation** to save the query.

## How to confirm it worked

* Choose a scorer span that contains an explanation in [** Logs**](https://www.braintrust.dev/app/~/logs) and find its exported row in S3.
* Compare the span's explanation with `output.metadata.rationale` for Logs (spans) or `explanation` for the Custom SQL query above.

## Notes

* To allow multiple automations in one project without updating the IAM trust policy for each automation, use a trust condition with `StringLike` and the external ID pattern `bt:<org-id>:<project-id>:*`.
* Changing an existing export keeps its checkpoint. To export historical spans, use Rewind. Rewind keeps existing files and can produce overlapping rows.
* If exports stall or show pending segments, contact Braintrust support for assistance.
* See [Export to S3](https://docs.braintrust.dev/admin/data-management/export.md).


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