GetShardIterator
Returns a shard iterator for the stream.
An iterator expires 5 minutes after being retrieved.
An iterator specifies the starting position in the shard from which the GetRecords method begins sequential record retrieval. The position is specified using the sequence number of a message in the shard.
The request must specify the iterator type.
For example, to retrieve an iterator that begins reading from a specific sequence number, specify the AT_SEQUENCE_NUMBER iterator type and provide the sequence number in the StartingSequenceNumber parameter. Alternatively, use the AFTER_SEQUENCE_NUMBER iterator type to get an iterator that starts reading from the record immediately after the one specified in the StartingSequenceNumber parameter. Use sequence numbers returned by the PutRecord, PutRecords, GetRecords, and DescribeStream methods.
To retrieve an iterator that begins reading from a specific timestamp, use the AT_TIMESTAMP iterator type and specify the starting time in the Timestamp parameter.
Use TRIM_HORIZON iterators to read from the oldest record in the shard, or LATEST iterators to start with the newest available record.
When reading records from a stream in a loop, first call GetShardIterator to get the shard iterator for your initial GetRecords request. For subsequent reads, you can use the NextShardIterator value returned in the GetRecords response.
Frequent calls to GetShardIterator may result in a ProvisionedThroughputExceededException.
If a shard has been closed (for example, due to resharding), the method returns an iterator for this shard’s last record.
Each open shard has a limit of 5 GetShardIterator requests per second.
Request
The request contains JSON-formatted data.
{
"ShardId": "string",
"ShardIteratorType": "string",
"StartingSequenceNumber": "string",
"StreamName": "string",
"Timestamp": number
}
Request options
| Option | Description |
|---|---|
ShardId |
ID of the target shard for the new iterator. Type: String Size: 1-128 characters.The possible values are: [a-zA-Z0-9_.-]+.Required: Yes. |
ShardIteratorType |
Shard iterator type. Type: ShardIteratorType. Allowed values:
|
StartingSequenceNumber |
Record sequence number. Used in conjunction with AT_SEQUENCE_NUMBER and AFTER_SEQUENCE_NUMBER iterator types.Type: String Size: 1-256 characters.Required: No. |
StreamName |
Data stream name. Type: String Size: 1-128 characters.Allowed values: lowercase letters, numbers, and hyphens (the first character must be a letter and the last character cannot be a hyphen). Required: No. |
Timestamp |
The timestamp specifying where sequential record retrieval begins. Used in conjunction with the AT_TIMESTAMP iterator type.Type: Integer |
Response
Successful requests return HTTP 200 with a JSON-formatted response body.
{
"Iterator": "string"
}
Response parameters
| Parameter | Description |
|---|---|
Iterator |
The starting position within the shard for sequential message retrieval. The iterator’s position corresponds to the sequence number of a record in the shard. Type: String Size: 1-512 characters.Required: Yes |
Errors
| Error | Description | HTTP code |
|---|---|---|
InvalidArgumentException |
The argument is invalid. See the error message for details. | 400 |
ProvisionedThroughputExceededException |
Insufficient throughput to process the request. | 400 |
ResourceNotFoundException |
The requested resource was not found. | 400 |
Errors common to all methods may occur.