---
title: Session Hydration
---

# Session Hydration

Sessions captured by the bitdrft platform are initially stored in cold storge and needs to be hydrated
first before session logs can be queried. Hydration can be done as follows:

1. Start hydration with
   [TimelineService.HydrateSession](../../api/bitdrift_public_unary_timeline_v1_TimelineService.md#HydrateSession).
2. Poll
   [TimelineService.GetHydrationStatus](../../api/bitdrift_public_unary_timeline_v1_TimelineService.md#GetHydrationStatus)
   until the session is ready.
3. Query the hydrated session with
   [TimelineService.GetSessionInfo](../../api/bitdrift_public_unary_timeline_v1_TimelineService.md#GetSessionInfo)
   or
   [TimelineService.GetSessionLogs](../../api/bitdrift_public_unary_timeline_v1_TimelineService.md#GetSessionLogs).

## Hydration State

The current hydration state can be queried at any time via
   [TimelineService.GetHydrationStatus](../../api/bitdrift_public_unary_timeline_v1_TimelineService.md#GetHydrationStatus).

This endpoint will return a `NOT_FOUND` error if there is no recorded hydration state, so if you query this first make sure to
handle this error case. Once the hydration has started this endpoint will return the status of the hydration job via the
[HydrationStatus](../../api/bitdrift_public_unary_timeline_v1_HydrationStatus.md) enum.

## Worked example

### 1. Request hydration

<section class="section-indent" markdown>
Start by asking the timeline service to hydrate a specific session. For a first attempt, keep
`force` set to `false` so the request can reuse any existing hydration work.

```bash
curl -X POST https://api-public.bitdrift.io/bitdrift.public.unary.timeline.v1.TimelineService/HydrateSession \
  -H "x-bitdrift-api-key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }'
```

Example response:

```json
{
  "ignored": false,
  "last_hydration_state": {
    "created_at": "2024-01-15T09:30:00Z",
    "hydration_status": "HYDRATING",
    "incremental": false,
    "started_at": "2024-01-15T09:30:00Z"
  },
  "success": true
}
```

Two fields matter immediately:

- `success` confirms the request was accepted.
- `ignored` tells you the service did not start a new job because the session is already hydrated or
  already hydrating. When that happens, inspect `last_hydration_state` and continue from there
  instead of retrying blindly.
</section>

### 2. Poll until the session is hydrated

<section class="section-indent" markdown>
Use the same `session_id` with `GetHydrationStatus` and wait until
`status.hydration_status == "HYDRATED"`.

```bash
curl -X POST https://api-public.bitdrift.io/bitdrift.public.unary.timeline.v1.TimelineService/GetHydrationStatus \
  -H "x-bitdrift-api-key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
```

Example ready response:

```json
{
  "status": {
    "created_at": "2024-01-15T09:30:00Z",
    "expiration_time": "2024-01-15T10:30:00Z",
    "finished_at": "2024-01-15T09:31:12Z",
    "hydration_status": "HYDRATED",
    "incremental": false,
    "started_at": "2024-01-15T09:30:00Z"
  }
}
```

If the status remains `HYDRATING`, wait and poll again. If it reaches `FAILED`, do not continue to
timeline reads because the session is not ready. Please reach out to bitdrift support if hydration fails.
</section>

### 3. Query the hydrated session

<section class="section-indent" markdown>
Once the session reports `HYDRATED`, you can query metadata or logs.

Fetch session metadata:

```bash
curl -X POST https://api-public.bitdrift.io/bitdrift.public.unary.timeline.v1.TimelineService/GetSessionInfo \
  -H "x-bitdrift-api-key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
```

Fetch the first page of session logs:

```bash
curl -X POST https://api-public.bitdrift.io/bitdrift.public.unary.timeline.v1.TimelineService/GetSessionLogs \
  -H "x-bitdrift-api-key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "page": 1,
    "per_page": 100
  }'
```

At that point the flow is complete: hydration makes the session ready, status confirms readiness,
and the timeline read APIs return the hydrated session data.
</section>

## Practical guidance

If you are building against the timeline API:

1. Treat `HydrateSession` as an asynchronous start-or-reuse call.
2. Use `GetHydrationStatus` as the readiness check before timeline reads.
3. Only set `force: true` when you intentionally want to request re-hydration of a session that may
   already have hydrated data.