Skip to content
delta-base docs

Read events from a stream

GET
/api/event-stores/{eventStoreName}/streams/{streamId}

Retrieves a chronological sequence of events from a specific stream. Each event represents a state change or action that occurred.

Key Concepts:

  • Events are ordered by their streamPosition (0-based index)
  • Each event has a unique eventId and globalPosition
  • The currentStreamVersion represents the latest version of the stream

Query Parameters:

  • expectedStreamVersion: Optionally verify the stream version matches expectations

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
eventStoreName
required

Event store name (automatically scoped to your organization)

string

Event store name (automatically scoped to your organization)

streamId
required

Unique identifier for the event stream (e.g., “user-123”, “order-456”, “cart-789”)

string

Unique identifier for the event stream (e.g., “user-123”, “order-456”, “cart-789”)

Query Parameters

Section titled “Query Parameters ”
expectedStreamVersion
string

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Stream events retrieved successfully. Returns events in chronological order with their metadata. If the stream does not exist, returns an empty events array with currentStreamVersion set to 0.

object
events
required
Array<object>
object
streamId
required
string
streamPosition
required
number
globalPosition
required
number
eventId
required
string
type
required
string
data
required
object
key
additional properties
nullable
metadata
object
key
additional properties
nullable
schemaVersion
required
string
transactionId
required
string
createdAt
required

ISO 8601 formatted timestamp in UTC

string
currentStreamVersion
required
number
Examples

User account events example

Shows a sequence of events for a user account, including creation and email update

{
  "events": [
    {
      "streamId": "user-123",
      "streamPosition": 0,
      "globalPosition": 1,
      "eventId": "evt_123",
      "type": "user.created",
      "data": {
        "userId": "123",
        "email": "user@example.com",
        "username": "johndoe"
      },
      "metadata": {
        "correlationId": "abc-123"
      },
      "schemaVersion": "1.0.0",
      "transactionId": "tx_123",
      "createdAt": "2023-01-15T12:30:45Z"
    },
    {
      "streamId": "user-123",
      "streamPosition": 1,
      "globalPosition": 2,
      "eventId": "evt_124",
      "type": "user.updated",
      "data": {
        "userId": "123",
        "email": "updated@example.com",
        "previousEmail": "user@example.com"
      },
      "metadata": {
        "correlationId": "abc-123"
      },
      "schemaVersion": "1.0.0",
      "transactionId": "tx_124",
      "createdAt": "2023-01-15T12:35:22Z"
    }
  ],
  "currentStreamVersion": 2
}

401

Section titled “401 ”

Unauthorized: Organization ID not found in authentication context

object
error
required
string
Allowed values: UNAUTHORIZED
message
required
string
Allowed values: Unauthorized: Organization ID not found in authentication context
Examples
{
  "error": "UNAUTHORIZED",
  "message": "Unauthorized: Organization ID not found in authentication context"
}

409

Section titled “409 ”

Version conflict when expectedStreamVersion doesn’t match

object
error
required
string
Allowed values: Version conflict
details
required
string
currentVersion
required
number
expectedVersion
required
number