Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

GetStream

Returns detailed information about a specific data capture stream for an Amazon Keyspaces table. The information includes the stream's Amazon Resource Name (ARN), creation time, current status, retention period, shard composition, and associated table details. This operation helps you monitor and manage the configuration of your Amazon Keyspaces data streams.

Request Syntax


{
   "maxResults": number,
   "nextToken": "string",
   "shardFilter": { 
      "shardId": "string",
      "type": "string"
   },
   "streamArn": "string"
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

maxResults

The maximum number of shard objects to return in a single GetStream request. Default value is 100. The minimum value is 1 and the maximum value is 100.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No

nextToken

An optional pagination token provided by a previous GetStream operation. If this parameter is specified, the response includes only records beyond the token, up to the value specified by maxResults.

Type: String

Length Constraints: Minimum length of 80. Maximum length of 3000.

Required: No

shardFilter

Optional filter criteria to apply when retrieving shards. You can filter shards based on their state or other attributes to narrow down the results returned by the GetStream operation.

Type: ShardFilter object

Required: No

streamArn

The Amazon Resource Name (ARN) of the stream for which detailed information is requested. This uniquely identifies the specific stream you want to get information about.

Type: String

Length Constraints: Minimum length of 37. Maximum length of 1024.

Required: Yes

Response Syntax


{
   "creationRequestDateTime": number,
   "keyspaceName": "string",
   "nextToken": "string",
   "shards": [ 
      { 
         "parentShardIds": [ "string" ],
         "sequenceNumberRange": { 
            "endingSequenceNumber": "string",
            "startingSequenceNumber": "string"
         },
         "shardId": "string"
      }
   ],
   "streamArn": "string",
   "streamLabel": "string",
   "streamStatus": "string",
   "streamViewType": "string",
   "tableName": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

creationRequestDateTime

The date and time when the request to create this stream was issued. The value is represented in ISO 8601 format.

Type: Timestamp

keyspaceName

The name of the keyspace containing the table associated with this stream. The keyspace name is part of the table's hierarchical identifier in Amazon Keyspaces.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 48.

Pattern: [a-zA-Z0-9][a-zA-Z0-9_]{0,47}

nextToken

A pagination token that can be used in a subsequent GetStream request. This token is returned if the response contains more shards than can be returned in a single response.

Type: String

Length Constraints: Minimum length of 80. Maximum length of 3000.

shards

An array of shard objects associated with this stream. Each shard contains a subset of the stream's data records and has its own unique identifier. The collection of shards represents the complete stream data.

Type: Array of Shard objects

streamArn

The Amazon Resource Name (ARN) that uniquely identifies the stream within Amazon Keyspaces. This ARN can be used in other API operations to reference this specific stream.

Type: String

Length Constraints: Minimum length of 37. Maximum length of 1024.

streamLabel

A timestamp that serves as a unique identifier for this stream, used for debugging and monitoring purposes. The stream label represents the point in time when the stream was created.

Type: String

streamStatus

The current status of the stream. Values can be ENABLING, ENABLED, DISABLING, or DISABLED. Operations on the stream depend on its current status.

Type: String

Valid Values: ENABLING | ENABLED | DISABLING | DISABLED

streamViewType

The format of the data records in this stream. Currently, this can be one of the following options:

NEW_AND_OLD_IMAGES - both versions of the row, before and after the change. This is the default.
NEW_IMAGE - the version of the row after the change.
OLD_IMAGE - the version of the row before the change.
KEYS_ONLY - the partition and clustering keys of the row that was changed.

Type: String

Valid Values: NEW_IMAGE | OLD_IMAGE | NEW_AND_OLD_IMAGES | KEYS_ONLY

tableName

The name of the table associated with this stream. The stream captures changes to rows in this Amazon Keyspaces table.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 48.

Pattern: [a-zA-Z0-9][a-zA-Z0-9_]{0,47}

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have sufficient access permissions to perform this operation.

This exception occurs when your IAM user or role lacks the required permissions to access the Amazon Keyspaces resource or perform the requested action. Check your IAM policies and ensure they grant the necessary permissions.

HTTP Status Code: 400

InternalServerException

The Amazon Keyspaces service encountered an unexpected error while processing the request.

This internal server error is not related to your request parameters. Retry your request after a brief delay. If the issue persists, contact AWS Support with details of your request to help identify and resolve the problem.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource doesn't exist or could not be found.

This exception occurs when you attempt to access a keyspace, table, stream, or other Amazon Keyspaces resource that doesn't exist or that has been deleted. Verify that the resource identifier is correct and that the resource exists in your account.

HTTP Status Code: 400

ThrottlingException

The request rate is too high and exceeds the service's throughput limits.

This exception occurs when you send too many requests in a short period of time. Implement exponential backoff in your retry strategy to handle this exception. Reducing your request frequency or distributing requests more evenly can help avoid throughput exceptions.

HTTP Status Code: 400

ValidationException

The request validation failed because one or more input parameters failed validation.

This exception occurs when there are syntax errors in the request, field constraints are violated, or required parameters are missing. To help you fix the issue, the exception message provides details about which parameter failed and why.

HTTP Status Code: 400