List Streams

Retrieve a paginated list of streams in a basin

GET /streams

List Streams

cURL

curl --request GET \
  --url https://api.example.com/streams

200

{
  "streams": [
    {
      "name": "<string>",
      "created_at": "<string>",
      "deleted_at": {}
    }
  ],
  "has_more": true
}

Overview

List all streams in a basin with optional filtering by prefix. Results are paginated with a maximum of 1000 streams per request.

Authentication

This endpoint requires authentication via the S2-Basin header containing your basin name.

Query Parameters

prefix · string

Filter to streams whose names begin with this prefix.

Example: logs/ would match logs/app and logs/system but not metrics/cpu

start_after · string

Filter to streams whose names lexicographically start after this string. Must be greater than or equal to the prefix if specified.

Used for pagination - pass the last stream name from the previous page to get the next page of results.

limit · number · default: "1000"

Number of results to return. Maximum value is 1000.

Response

streams · StreamInfo[]

Array of matching streams.

Show StreamInfo

name · string

Stream name unique to the basin. Between 1 and 512 bytes in length.

created_at · string

Creation time in RFC 3339 format.

Example: 2024-01-15T10:30:00Z

deleted_at · string | null

Deletion time in RFC 3339 format if the stream is being deleted, otherwise null.

has_more · boolean

Indicates that there are more results that match the criteria. Use the last stream name with start_after to retrieve the next page.

Example Request

cURL

curl -X GET 'https://{basin}.b.aws.s2.dev/v1/streams?prefix=logs/&limit=100' \
  -H 'S2-Basin: my-basin' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

{
  "streams": [
    {
      "name": "logs/application",
      "created_at": "2024-01-15T10:30:00Z",
      "deleted_at": null
    },
    {
      "name": "logs/system",
      "created_at": "2024-01-14T08:15:00Z",
      "deleted_at": null
    }
  ],
  "has_more": false
}

Pagination Example

To retrieve all streams with pagination:

# First request
curl -X GET 'https://{basin}.b.aws.s2.dev/v1/streams?limit=1000' \
  -H 'S2-Basin: my-basin'

# If has_more is true, get next page
curl -X GET 'https://{basin}.b.aws.s2.dev/v1/streams?start_after=last-stream-name&limit=1000' \
  -H 'S2-Basin: my-basin'