Query events for a specific stream with filtering options

GET

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

• Production

Retrieves events for a specific stream with flexible filtering options.

Key Features:

• Filter stream events by type, timeframes, and other criteria
• Paginate results with limit and offset parameters
• Sort by different fields (global_position, created_at, stream_position)
• Get total count for pagination (when include_count=true)

This endpoint is particularly useful for:

• Viewing the history of a specific entity or aggregate
• Debugging issues with a particular stream
• Auditing changes to a specific entity over time

Authorizations

• Bearer

Parameters

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. Supports hyphen (-), underscore (_), or colon (:) as delimiters. The first segment before the delimiter is used as the stream type.

string

Unique identifier for the event stream. Supports hyphen (-), underscore (_), or colon (:) as delimiters. The first segment before the delimiter is used as the stream type.

Query Parameters

type

Any of:

string

string

Array<string>

Array<string>

eventId

string

transactionId

string

fromPosition

string

toPosition

string

fromDate

string format: date-time

toDate

string format: date-time

phase

string

includeArchived

string

limit

string

offset

string

sortBy

string

Allowed values: globalPosition createdAt streamPosition

sortDirection

string

Allowed values: asc desc

includeCount

string

Responses

200

Stream events retrieved successfully. If the stream does not exist, returns an empty events array

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

pagination

required

object

limit

required

number

offset

required

number

total

number

hasMore

required

boolean

Examples

Basic query result for a stream

Example of query results for a user stream

{
  "events": [
    {
      "streamId": "user-123",
      "streamPosition": 0,
      "globalPosition": 42,
      "eventId": "evt_123",
      "type": "user.created",
      "data": {
        "userId": "123",
        "email": "user@example.com"
      },
      "metadata": {
        "correlationId": "abc-123"
      },
      "schemaVersion": "1.0.0",
      "transactionId": "tx_123",
      "createdAt": "2023-01-15T12:30:45Z"
    },
    {
      "streamId": "user-123",
      "streamPosition": 1,
      "globalPosition": 43,
      "eventId": "evt_456",
      "type": "user.updated",
      "data": {
        "userId": "123",
        "email": "updated@example.com"
      },
      "metadata": {
        "correlationId": "def-456"
      },
      "schemaVersion": "1.0.0",
      "transactionId": "tx_456",
      "createdAt": "2023-01-15T13:45:22Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2,
    "hasMore": false
  }
}

400

Invalid query parameters

object

error

required

string

Allowed values: Invalid request body

details

required

Array<object>

object

code

required

string

message

required

string

path

required

Array

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"
}