View as Markdown

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:

Start hydration with TimelineService.HydrateSession.
Poll TimelineService.GetHydrationStatus until the session is ready.
Query the hydrated session with TimelineService.GetSessionInfo or TimelineService.GetSessionLogs.

Hydration State¶

The current hydration state can be queried at any time via TimelineService.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 enum.

Worked example¶

1. Request hydration¶

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.

2. Poll until the session is hydrated¶

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.

3. Query the hydrated session¶

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.

Practical guidance¶

If you are building against the timeline API:

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