GET
/
streams
/
{stream}
/
records
curl --request GET \
  --url https://{basin}.b.aws.s2.dev/v1/streams/{stream}/records \
  --header 'Authorization: Bearer <token>'
{
  "records": [
    {
      "body": "<string>",
      "headers": [
        [
          "<string>"
        ]
      ],
      "seq_num": 1,
      "timestamp": 1
    }
  ],
  "tail": null
}

Reads may start at one of:

  • seq_num
  • timestamp
  • tail_offset (the number of records before the tail)

The first record that is returned will be the earliest on the stream that is greater than or equal to the requested starting point.

You may limit the read by total count or bytes size, or until a specific timestamp.

With a ReadSession (available via most SDKs) or using SSE, you are able to read in a streaming fashion. If a limit is not specified and the end of the stream is reached, the session goes into real-time tailing mode and will return records as they are appended to the stream.

Reading records written within the last 20 seconds is expected to take single-digit milliseconds. Otherwise, the time-to-first-byte can take up to 200 milliseconds.

​
SSE

Server push with Server-Sent-Events (SSE) is supported. Clients can request an SSE response by setting the Accept: text/event-stream header.

  curl --request GET \
  --url 'https://hello-world.b.aws.s2.dev/v1/streams/test/records?seq_num=0' \
  --header "Authorization: Bearer ${S2_ACCESS_TOKEN}" \
  --header 'Accept: text/event-stream'

event: batch
id: 4,5,74
data: {"records":[{"seq_num":4,"timestamp":1750101582144,"body":"hello"}],"tail":{"seq_num":5,"timestamp":1750101582144}}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
s2-format
enum<string>

Defines the treatment of blob fields when exchanging records as JSON. Use raw (default) if you are working with Unicode data — storage will be in UTF-8. Use base64 for safe transmission and efficient storage of binary data.

Available options:
raw,
base64

Path Parameters

​
stream
string
required

Stream name.

Query Parameters

​
seq_num
integer

Start from a sequence number.

Required range: x >= 0
​
timestamp
integer

Start from a timestamp.

Required range: x >= 0
​
tail_offset
integer

Start from number of records before the next sequence number.

Required range: x >= 0
​
count
integer

Limit total records to return. If this is provided, tailing will be disabled.

Required range: x >= 0
​
bytes
integer

Limit total metered bytes to return. If this is provided, tailing will be disabled.

Required range: x >= 0
​
until
integer

Exclusive timestamp to read until. If this is provided, tailing will be disabled.

Required range: x >= 0

Response

200
application/json

The response is of type object.