GET
/
streams
/
{stream}
/
records
Read 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.
Reading records is linearizable — if an append has received an acknowledgment before the read request is made, the response will reflect the write.
You may limit the read by total count or bytes size, or until a specific timestamp.
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.
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.

​
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 access token.

Headers

​
s2-format
enum<string>

Defines the interpretation of record data (header name, header value, and body) with the JSON content type. Use raw (default) for efficient transmission and storage of Unicode data — storage will be in UTF-8. Use base64 for safe transmission with 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
​
clamp
boolean

Clamp the start position at the tail position. If set, the read will start at the tail of the stream if the requested position is greater than it.

Response

​
records
object[]
required

Records that are durably sequenced on the stream, retrieved based on the requested criteria. This can only be empty in response to a regular (non-SSE) read, if the request cannot be satisfied without violating an explicit limit.

​
tail
object | null

Sequence number that will be assigned to the next record on the stream, and timestamp of the last record. This will only be present when reading recent records.