Skip to main content
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. You may bound the read by total count or bytes size, or until a specific timestamp.
for records written in the last 20 seconds for an Express stream will be single-digit milliseconds. Otherwise, it can be up to 200 milliseconds.
Reading records is linearizable — if an append has received an acknowledgment before the read request is made, the response will reflect the write.

​
Follow live updates

Long polling is supported by providing a non-zero wait=<seconds>. A response will only be sent when records are available or the wait elapses. With a ReadSession (available via most SDKs, or using SSE), you are able to read in a streaming fashion. Once the tail of the stream is reached, a session will follow in real-time for new records if either no bounds are provided (count, bytes, until), or wait is non-zero. In any case, a reader may follow live updates only when the wait is non-zero, whether by default or an override.
Nature of requestDefault waitDefault semantics
Unary0No long polling
Session 0No wait for new records
Session ∞Infinite wait between records

​
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}}
Any Error message will terminate the stream.

​
Starting point past tail

is returned in the below cases:
May followclampConditions for 416
👍false (default)seq_num > tail.seq_num or timestamp > tail.timestamp
👎-empty stream, seq_num >= tail.seq_num, or timestamp > tail.timestamp
When the intent is either to follow from a point, or if that does not exist yet, from the next record that becomes available on the stream, you can clamp=true.

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
​
clamp
boolean

Start reading from the tail if the requested position is beyond it. Otherwise, a 416 Range Not Satisfiable response is returned.

​
count
integer

Record count limit. Non-streaming reads are capped by the default limit of 1000 records.

Required range: x >= 0
​
bytes
integer

Metered bytes limit. Non-streaming reads are capped by the default limit of 1 MiB.

Required range: x >= 0
​
until
integer

Exclusive timestamp to read until.

Required range: x >= 0
​
wait
integer

Duration in seconds to wait for new records. The default duration is 0 if there is a bound on count, bytes, or until, and otherwise infinite. Non-streaming reads are always bounded on count and bytes, so you can achieve long poll semantics by specifying a non-zero duration up to 60 seconds. In the context of an SSE or S2S streaming read, the duration will bound how much time can elapse between records throughout the lifetime of the session.

Required range: x >= 0

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 unary read (i.e. not SSE), if the request cannot be satisfied without violating an explicit bound (count, bytes, or until).

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