---
title: Amazon S3
description: Store session data only in your own S3 bucket, with the console reading it back from there.
---

With S3 connected, new sessions are written to your bucket and nowhere else. When someone opens a session in the console, Surface reads it from your bucket. How long the data is kept becomes your bucket's lifecycle policy.

## Before you begin

- An S3 bucket.
- An access key and secret key that can `GetObject`, `PutObject`, `DeleteObject`, and `ListBucket` on it.
- For MinIO, Ceph, or another S3-compatible service: its endpoint URL.

## Connect

1. **Open the setup window**

    **Extensions**, then **Amazon S3** under Cloud Extensions, then **Configure**.

2. **Choose the provider**

    `aws` for Amazon S3. `compatible` for MinIO, Ceph, and similar.

3. **Fill in the required fields**

    | Field | Notes |
    | --- | --- |
    | **Bucket** | Bucket name |
    | **Access key ID** | Secret |
    | **Secret access key** | Secret |
    | **Endpoint URL** | `compatible` only, for example `https://minio.internal:9000` |

4. **Test and enable**

    Click **Test connection** and wait for "Amazon S3 connection works". Then **Save & Enable**.

## Advanced options

| Field | Default | Change it when |
| --- | --- | --- |
| **Prefix** | `prompts` | You want a different top-level folder |
| **Region** | `us-east-1` | AWS only, and your bucket is elsewhere |
| **Engine** | `parquet` | Set `athena` to query session data with SQL through Amazon Athena |
| **Athena workgroup** | `primary` | Athena engine only. Needs Athena engine version 3 |
| **Athena database** | `surface_prompts` | Athena engine only. Created on first configure |
| **Athena output** | `athena-results/` under the prefix | Athena engine only |
| **Use path style** | on | `compatible` only |

Athena is Amazon's service for running SQL over files in S3. If you are unsure, leave the engine as `parquet` and ask whoever owns your AWS account.

## What lands in the bucket

```
<prefix>/transcripts/org_id=<your org>/<session id>/part-00000-00099-<digest>.json.gz
<prefix>/sessions/org_id=<your org>/<session id>/...parquet
<prefix>/messages/org_id=<your org>/<session id>/...parquet
<prefix>/usage/org_id=<your org>/<session id>/...parquet
```

`transcripts` holds the conversations. The other three folders hold summaries the console uses for lists and search. Set lifecycle rules on the prefix as a whole.

:::warning
If the bucket becomes unreachable, new sessions cannot be saved. Surface does not fall back to its own storage. After rotating keys, run **Test connection** again.
:::

## What happens next

The next session recorded on any laptop is written to your bucket. Open it on the [Sessions](/surface/sessions/review) page: if the trace loads, reads from the bucket work. Sessions recorded before you enabled S3 stay in SuperAlign storage until they expire.

## Next steps

- [Splunk](/surface/extensions/cloud/splunk) to also send a copy to your index
- [Data handling](/surface/admin/data-handling) for what retention now depends on