# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryterra.co/health-and-fitness-api/integration-setup/setting-up-data-destinations/cloud-storage-s3-gcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.