Read

Reading data in Litebase lets you access the value of any key — either as it exists now or at any point in the past. Every value is versioned, so you can retrieve current state, audit history, or reconstruct previous snapshots.

This guide walks through how to read key/value data, fetch historical versions, and use reads as part of version-aware workflows.

1. Read the latest value

To fetch the most recent value of a key, send an HTTP GET request:

curl https://api.litebase.io/v1/kv/user.abc123.profile \
  -H "Authorization: Bearer $LITEBASE_API_KEY"

Example response:

{
  "key": "user.abc123.profile",
  "value": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "status": "active"
  },
  "time": "2025-04-06T09:00:00Z",
  "tx": "tx_9c012abc",
  "version": 4
}

This returns the latest committed version of the key, along with the transaction metadata.

2. Read a historical version

To query the value as it existed at a specific point in time, use the as_of parameter:

By transaction ID:

curl "https://api.litebase.io/v1/kv/user.abc123.profile?as_of=tx_7a29d1a3" \
  -H "Authorization: Bearer $LITEBASE_API_KEY"

By timestamp:

curl "https://api.litebase.io/v1/kv/user.abc123.profile?as_of=2025-04-01T00:00:00Z" \
  -H "Authorization: Bearer $LITEBASE_API_KEY"

This gives you the exact state of the key as of that point — useful for debugging, audit, or replay-based workflows.

3. Read with context

Every read response includes:

• key: the key name
• value: the value at the requested time
• time: when the value was written
• tx: the transaction ID
• version: the version number of the write

These fields make it easy to correlate data with stream events, state transitions, or timeline snapshots.

4. Handle missing keys

If the key does not exist at the given point in time, you'll receive a 404 response:

{
  "error": "not_found",
  "message": "Key not found as of given time"
}

This usually means:

• The key was created after the requested as_of time
• The key has never been written to