> 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/destinations/mongodb.md).

# MongoDB

Store full Terra payloads in your MongoDB database, with the collections, indices and document IDs Terra creates.

Terra can store health data directly in your [MongoDB](https://www.mongodb.com/) database, with full payloads stored inline (no external URLs to fetch).

## Before you begin

* A MongoDB instance reachable from Terra's servers. Terra supports both `mongodb://` and `mongodb+srv://` connection schemes.

{% hint style="warning" %}
**Security:** Restrict inbound connections to Terra's IP addresses listed on the [Destinations page](https://docs.tryterra.co/destinations/setting-up-data-destinations.md#ip-allowlist). If using MongoDB Atlas, add these IPs to your [IP Access List](https://www.mongodb.com/docs/atlas/security/ip-access-list/). Use a strong, unique password and require TLS for connections.
{% endhint %}

## Create a database user

Create a database user with read/write access to your target database.

## Add the destination in Terra

On the [Connections page](https://dashboard.tryterra.co/dashboard/connections) in your Terra dashboard, click **Add New**, add the MongoDB destination, and enter:

* **Host** (e.g. `cluster0.abc123.mongodb.net`)
* **Database name**
* **Username and password**
* **Connection scheme** (`mongodb` or `mongodb+srv`)

## What Terra writes

Terra creates collections automatically and adds indices on first write.

### Collections

| Collection     | Contents                                                 | Document ID             |
| -------------- | -------------------------------------------------------- | ----------------------- |
| `user_events`  | Auth events (auth success, deauth, access revoked, etc.) | `{user_id, event_time}` |
| `athlete`      | Athlete profile data                                     | `user_id`               |
| `activity`     | Activity data                                            | `{user_id, start_time}` |
| `body`         | Body metrics                                             | `{user_id, start_time}` |
| `daily`        | Daily summary data                                       | `{user_id, start_time}` |
| `sleep`        | Sleep data                                               | `{user_id, start_time}` |
| `nutrition`    | Nutrition data                                           | `{user_id, start_time}` |
| `menstruation` | Menstruation data                                        | `{user_id, start_time}` |

### Indices

Terra creates the following indices automatically:

* **`user_events` and `athlete`:** `user.user_id` (ascending), `user.reference_id` (ascending)
* **Data collections** (activity, body, daily, sleep, nutrition, menstruation): `metadata.start_time` (descending), `metadata.end_time` (descending)

### Document format

All documents include the full data payload inline. There are no external URLs to download. Each document includes a `user` object with the user's details.

**Data event example:**

```json
{
  "_id": { "user_id": "abc123", "start_time": "2026-03-12T06:00:00Z" },
  "user": { "user_id": "abc123", "reference_id": "your-ref", "provider": "FITBIT" },
  "metadata": { "start_time": "2026-03-12T06:00:00Z", "end_time": "2026-03-12T07:00:00Z" },
  "duration_seconds": 3600,
  "active_duration_seconds": 1800
}
```

Documents are upserted: if a document with the same ID already exists, it is replaced with the latest data.

## Next steps

* [User authentication](https://docs.tryterra.co/unified-api/authentication-flow.md): link a user's wearable so events start flowing.
* [Event delivery](https://docs.tryterra.co/destinations/events.md): see what each delivery status means and how retries work.
* [Health data events](https://docs.tryterra.co/unified-api/receiving-data-updates.md): process the data Terra delivers.
