> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/unified-api/integration-setup/setting-up-data-destinations/cloud-storage-s3-gcp.md).

# Cloud storage (S3, GCS, Azure Blob)

Terra can dump raw data payloads directly into your cloud storage bucket. Supported providers: **AWS S3**, **Google Cloud Storage (GCS)**, and **Azure Blob Storage**.

## Authentication

{% tabs %}
{% tab title="AWS S3" %}
[Create an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) with write access to your target bucket. [Attach a policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) granting at minimum `s3:PutObject` on your bucket.

Enter the **bucket name**, **region**, **Access Key ID**, and **Secret Access Key** in the Terra Dashboard when adding the S3 destination.
{% endtab %}

{% tab title="GCS" %}
[Create a service account](https://developers.google.com/workspace/guides/create-credentials#service-account) and grant it the **Storage Object Admin** role (`roles/storage.objectAdmin`) on your target bucket. This role is required because Terra overwrites existing files on redelivery, which needs both `storage.objects.create` and `storage.objects.delete` permissions. Download the JSON credentials file.

You can grant the role via the console or with:

```bash
gsutil iam ch serviceAccount:YOUR_SA@YOUR_PROJECT.iam.gserviceaccount.com:objectAdmin gs://YOUR_BUCKET
```

Enter the **bucket name** and upload the credentials JSON in the Terra Dashboard when adding the GCS destination.
{% endtab %}

{% tab title="Azure Blob" %}
Generate a [SAS URL](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview) for your storage account that grants write access to your target container.

Enter the **SAS URL** and **container name** in the Terra Dashboard when adding the Azure Blob destination.
{% endtab %}
{% endtabs %}

## Data Structure

All cloud storage destinations use the same folder structure:

```
2022-03-16/
  {event_type}/
    {user_id}-{timestamp}.json       # Auth/misc events
  {data_type}/
    {user_id}-{start_time}.json      # Data events (activity, sleep, etc.)
```

**Examples:**

```
2022-03-16/auth/abc123-2026-03-12T14:30:00Z.json
2022-03-16/activity/abc123-2026-03-12T06:00:00Z.json
2022-03-16/sleep/abc123-2026-03-11T22:00:00Z.json
```

* **Data events** (activity, sleep, body, etc.) are placed under a folder named after the data type, with each file named `{user_id}-{start_time}.json`.
* **Auth and other events** are placed under a folder named after the event type, with each file named `{user_id}-{timestamp}.json`.
* The `2022-03-16` prefix corresponds to the API version.

{% hint style="info" %}
**FIT files (S3 only):** For activity data that includes raw FIT files, Terra uploads both the JSON payload and the original `.fit` file alongside it (e.g. `2022-03-16/activity/abc123-2026-03-12T06:00:00Z.fit`).
{% endhint %}