gRPC API

​

AccountService

Operate on an S2 account.

Method Name	Request Type	Response Type	Description	Options
ListBasins	ListBasinsRequest	ListBasinsResponse	List basins.	idempotency_level: NO_SIDE_EFFECTS
CreateBasin	CreateBasinRequest	CreateBasinResponse	Create a new basin. Provide a client request token with the S2-Request-Token header for idempotent retry behaviour.	idempotency_level: IDEMPOTENT
DeleteBasin	DeleteBasinRequest	DeleteBasinResponse	Delete a basin. Basin deletion is asynchronous, and may take a few minutes to complete.	idempotency_level: IDEMPOTENT
ReconfigureBasin	ReconfigureBasinRequest	ReconfigureBasinResponse	Update basin configuration.	idempotency_level: IDEMPOTENT
GetBasinConfig	GetBasinConfigRequest	GetBasinConfigResponse	Get basin configuration.	idempotency_level: NO_SIDE_EFFECTS

​

BasinService

Operate on an S2 basin.

Method Name	Request Type	Response Type	Description	Options
ListStreams	ListStreamsRequest	ListStreamsResponse	List streams.	idempotency_level: NO_SIDE_EFFECTS
CreateStream	CreateStreamRequest	CreateStreamResponse	Create a stream. Provide a client request token with the S2-Request-Token header for idempotent retry behaviour.	idempotency_level: IDEMPOTENT
DeleteStream	DeleteStreamRequest	DeleteStreamResponse	Delete a stream. Stream deletion is asynchronous, and may take a few minutes to complete.	idempotency_level: IDEMPOTENT
GetStreamConfig	GetStreamConfigRequest	GetStreamConfigResponse	Get stream configuration.	idempotency_level: NO_SIDE_EFFECTS
ReconfigureStream	ReconfigureStreamRequest	ReconfigureStreamResponse	Update stream configuration.	idempotency_level: IDEMPOTENT

​

StreamService

Operate on an S2 stream.

Method Name	Request Type	Response Type	Description	Options
CheckTail	CheckTailRequest	CheckTailResponse	Check the sequence number that will be assigned to the next record on a stream.	idempotency_level: NO_SIDE_EFFECTS
Append	AppendRequest	AppendResponse	Append a batch of records to a stream.	None
AppendSession	AppendSessionRequest stream	AppendSessionResponse stream	Append batches of records to a stream continuously, while guaranteeing pipelined requests are processed in order. If any request fails, the session is terminated.	None
Read	ReadRequest	ReadResponse	Retrieve a batch of records from a stream.	idempotency_level: NO_SIDE_EFFECTS
ReadSession	ReadSessionRequest	ReadSessionResponse stream	Retrieve batches of records from a stream continuously.	idempotency_level: NO_SIDE_EFFECTS

​

AppendInput

Input for append requests.

Field	Type	Label	Description
stream	string		Stream name. Optional for subsequent requests in the session.
records	AppendRecord	repeated	Batch of records to append atomically, which must contain at least one record, and no more than 1000. The total size of a batch of records may not exceed 1MiB of metered bytes.
match_seq_num	uint64	optional	Enforce that the sequence number issued to the first record matches.
fencing_token	bytes	optional	Enforce a fencing token which must have been previously set by a fence command record.

​

AppendOutput

Output from append response.

Field	Type	Label	Description
start_seq_num	uint64		Sequence number of first record appended.
end_seq_num	uint64		Sequence number of last record appended + 1. end_seq_num - start_seq_num will be the number of records in the batch.
next_seq_num	uint64		Sequence number of last durable record on the stream + 1. This can be greater than end_seq_num in case of concurrent appends.

​

AppendRecord

Record to be appended to a stream.

Field	Type	Label	Description
timestamp	uint64	optional	Timestamp for this record in milliseconds since Unix epoch. The service ensures monotonicity by adjusting it up if necessary to the maximum observed timestamp. A timestamp detected to be in the future will be adjusted down. If not provided, the semantics depend on the stream’s require_client_timestamps config.
headers	Header	repeated	Series of name-value pairs for this record.
body	bytes		Body of this record.

​

AppendRequest

Append request.

Field	Type	Label	Description
input	AppendInput		Request parameters for an append.

​

AppendResponse

Append response.

Field	Type	Label	Description
output	AppendOutput		Response details for an append.

​

AppendSessionRequest

Append session request.

Field	Type	Label	Description
input	AppendInput		Request parameters for an append.

​

AppendSessionResponse

Append session response.

Field	Type	Label	Description
output	AppendOutput		Response details for an append.

​

BasinConfig

Basin configuration.

Field	Type	Label	Description
default_stream_config	StreamConfig		Default stream configuration.
create_stream_on_append	bool		Create stream on append if it doesn’t exist, using the default stream configuration.

​

BasinInfo

Basin information.

Field	Type	Label	Description
name	string		Basin name.
scope	BasinScope		Basin scope.
state	BasinState		Basin state.

​

CheckTailRequest

Check tail request.

Field	Type	Label	Description
stream	string		Stream name.

​

CheckTailResponse

Check tail response.

Field	Type	Label	Description
next_seq_num	uint64		Sequence number that will be assigned to the next record on the stream.

​

CreateBasinRequest

Create basin request.

Field	Type	Label	Description
basin	string		Basin name, which must be globally unique. It can be omitted to let the service assign a unique name. The name must be between 8 and 48 characters, comprising lowercase letters, numbers and hyphens. It cannot begin or end with a hyphen.
config	BasinConfig		Basin configuration.
scope	BasinScope		Basin scope.

​

CreateBasinResponse

Create basin response.

Field	Type	Label	Description
info	BasinInfo		Information about the newly created basin.

​

CreateStreamRequest

Create stream request.

Field	Type	Label	Description
stream	string		Stream name, which must be unique within the basin. It can be an arbitrary string upto 512 characters. Backslash (/) is recommended as a delimiter for hierarchical naming.
config	StreamConfig		Configuration for the new stream.

​

CreateStreamResponse

Create stream response.

Field	Type	Label	Description
info	StreamInfo		Information about the newly created stream.

​

DeleteBasinRequest

Delete basin request.

Field	Type	Label	Description
basin	string		Name of the basin to delete.

​

DeleteBasinResponse

Delete basin response.

​

DeleteStreamRequest

Delete stream request.

Field	Type	Label	Description
stream	string		Stream name.

​

DeleteStreamResponse

Delete stream response.

​

GetBasinConfigRequest

Get basin configuration request.

Field	Type	Label	Description
basin	string		Basin name.

​

GetBasinConfigResponse

Get basin configuration response.

Field	Type	Label	Description
config	BasinConfig		Basin configuration.

​

GetStreamConfigRequest

Get stream configuration request.

Field	Type	Label	Description
stream	string		Stream name.

​

GetStreamConfigResponse

Get stream configuration response.

Field	Type	Label	Description
config	StreamConfig		Stream configuration.

​

Header

Headers add structured information to a record as name-value pairs.

Field	Type	Label	Description
name	bytes		Header name blob. The name cannot be empty, with the exception of an S2 command record.
value	bytes		Header value blob.

​

ListBasinsRequest

List basins request.

Field	Type	Label	Description
prefix	string		List basin names that begin with this prefix.
start_after	string		Only return basins names that lexicographically start after this name. This can be the last basin name seen in a previous listing, to continue from there. It must be greater than or equal to the prefix if specified.
limit	uint64	optional	Number of results, up to a maximum of 1000.

​

ListBasinsResponse

List basins response.

Field	Type	Label	Description
basins	BasinInfo	repeated	Matching basins.
has_more	bool		If set, indicates there are more results that can be listed with start_after.

​

ListStreamsRequest

List streams request.

Field	Type	Label	Description
prefix	string		List stream names that begin with this prefix.
start_after	string		Only return stream names that lexicographically start after this name. This can be the last stream name seen in a previous listing, to continue from there. It must be greater than or equal to the prefix if specified.
limit	uint64	optional	Number of results, up to a maximum of 1000.

​

ListStreamsResponse

List streams response.

Field	Type	Label	Description
streams	StreamInfo	repeated	Matching streams.
has_more	bool		If set, indicates there are more results that can be listed with start_after.

​

ReadLimit

If both count and bytes are specified, either limit may be hit.

Field	Type	Label	Description
count	uint64	optional	Record count limit.
bytes	uint64	optional	Metered bytes limit.

​

ReadOutput

Output from read response.

Field	Type	Label	Description
batch	SequencedRecordBatch		Batch of records. This batch can be empty only if a limit was specified in the associated read request, and either the first record that could have been retrieved would violate the limit, or the requested start_seq_num is the next_seq_num for the stream.
first_seq_num	uint64		Sequence number for the first record on this stream, in case the requested start_seq_num was smaller.
next_seq_num	uint64		Sequence number for the next record on this stream, in case the requested start_seq_num was larger.

​

ReadRequest

Read request.

Field	Type	Label	Description
stream	string		Stream name.
start_seq_num	uint64		Starting sequence number (inclusive).
limit	ReadLimit		Limit on how many records can be returned upto a maximum of 1000, or 1MiB of metered bytes.

​

ReadResponse

Read response.

Field	Type	Label	Description
output	ReadOutput		Response details for a read.

​

ReadSessionRequest

Read session request.

Field	Type	Label	Description
stream	string		Stream name.
start_seq_num	uint64		Starting sequence number (inclusive).
limit	ReadLimit		Limit on how many records can be returned. When a limit is specified, the session will be terminated as soon as the limit is met, or when the current tail of the stream is reached — whichever occurs first. If no limit is specified, the session will remain open after catching up to the tail, and continue tailing as new messages are written to the stream.
heartbeats	bool		Heartbeats can be enabled to monitor end-to-end session health. A heartbeat will be sent when the initial switch to real-time tailing happens, as well as when no records are available at a randomized interval between 5 and 15 seconds.

​

ReadSessionResponse

Read session response.

Field	Type	Label	Description
output	ReadOutput	optional	Response details for a read. This will not be set in case of a heartbeat message.

​

ReconfigureBasinRequest

Reconfigure basin request.

Field	Type	Label	Description
basin	string		Basin name.
config	BasinConfig		Basin configuration.
mask	google.protobuf.FieldMask		Specifies the pieces of configuration being updated. See https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask

​

ReconfigureBasinResponse

Reconfigure basin response.

Field	Type	Label	Description
config	BasinConfig		Basin configuration.

​

ReconfigureStreamRequest

Reconfigure stream request.

Field	Type	Label	Description
stream	string		Stream name.
config	StreamConfig		Stream configuration with updated values.
mask	google.protobuf.FieldMask		Specifies the pieces of configuration being updated. See https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask

​

ReconfigureStreamResponse

Reconfigure stream response.

Field	Type	Label	Description
config	StreamConfig		Stream configuration.

​

SequencedRecord

Record retrieved from a stream.

Field	Type	Label	Description
seq_num	uint64		Sequence number assigned to this record.
timestamp	uint64		Timestamp for this record in milliseconds since Unix epoch.
headers	Header	repeated	Series of name-value pairs for this record.
body	bytes		Body of this record.

​

SequencedRecordBatch

A batch of sequenced records.

Field	Type	Label	Description
records	SequencedRecord	repeated	Batch of sequenced records.
next_seq_num	uint64	optional	Sequence number that will be assigned to the next record in the stream. It will only be present when reading recent records.

​

StreamConfig

Stream configuration.

Field	Type	Label	Description
storage_class	StorageClass		Storage class for recent writes. This is the main cost:performance knob in S2.
age	uint64		Age in seconds for automatic trimming of records older than this threshold. If set to 0, the stream will have infinite retention.
require_client_timestamps	bool	optional	Controls how to handle timestamps when they are not provided by the client. If this is false (or not set), the record’s arrival time will be assigned as its timestamp. If this is true, then any append without a client-specified timestamp will be rejected as invalid.

​

StreamInfo

Stream information.

Field	Type	Label	Description
name	string		Stream name.
created_at	uint32		Creation time in seconds since Unix epoch.
deleted_at	uint32	optional	Deletion time in seconds since Unix epoch, if the stream is being deleted.

​

BasinScope

Basin scope.

Name	Number	Description
BASIN_SCOPE_UNSPECIFIED	0	Unspecified basin scope.
BASIN_SCOPE_AWS_US_EAST_1	1	aws us-east-1 region.

​

BasinState

Current state of the basin.

Name	Number	Description
BASIN_STATE_UNSPECIFIED	0	Unspecified.
BASIN_STATE_ACTIVE	1	Basin is active.
BASIN_STATE_CREATING	2	Basin is being created.
BASIN_STATE_DELETING	3	Basin is being deleted.

​

StorageClass

Storage class for recent writes.

Name	Number	Description
STORAGE_CLASS_UNSPECIFIED	0	Unspecified, which is currently overridden to STORAGE_CLASS_EXPRESS.
STORAGE_CLASS_STANDARD	1	Standard, which offers end-to-end latencies under 500 ms.
STORAGE_CLASS_EXPRESS	2	Express, which offers end-to-end latencies under 50 ms.