Get started with queues using the AWS CLI
This walkthrough uses the AWS CLI to create a queue on an On-demand stream and work through the receive-and-acknowledge cycle. You create a stream and add a few records, create a queue, receive records, extend the visibility timeout of a record, acknowledge the records you finish, and then delete the queue and the stream.
Before you begin, install and configure the AWS CLI. For instructions, see
Tutorial: Install and configure the AWS CLI for Kinesis Data Streams. You also need permission for the
queue actions, including kinesis:AssociateStreamsWithQueue on the stream. For
more information, see IAM permissions for queues. Queue
operations use their own interface VPC endpoint service, separate from the stream endpoint.
For more information, see Use interface VPC endpoints for Kinesis Data Streams. The example resource names,
Amazon Resource Names (ARNs), and receipt handles in this walkthrough are illustrative.
Replace them with the values from your own output.
Step 1: Create a stream and add records
A queue works only on an On-demand stream. Create an On-demand stream and add a few records to it. For the full procedure, see Tutorial: Perform basic Kinesis Data Streams operations using the AWS CLI.
Create the stream:
aws kinesis create-stream \ --stream-name my-stream \ --stream-mode-details StreamMode=ON_DEMAND
Add a few records. To pass the record data as plain text and have the AWS CLI return
binary values as base64, use --cli-binary-format raw-in-base64-out (or set
cli_binary_format = raw-in-base64-out in your AWS CLI configuration file):
aws kinesis put-record \ --stream-name my-stream \ --partition-key user-1 \ --data "hello world" \ --cli-binary-format raw-in-base64-out
Step 2: Create a queue
Create a queue with one StreamConfigurationList entry that associates
the queue with your stream. The list must contain exactly one entry. Set the starting
position in that entry, and set the queue default visibility timeout in
QueueAttributes. The default starting position is LATEST.
aws kinesis create-queue \ --queue-name my-queue \ --stream-configuration-list '[ { "StreamARN": "arn:aws:kinesis:us-west-2:111122223333:stream/my-stream", "StartingPosition": { "Type": "TRIM_HORIZON" } } ]' \ --queue-attributes '{ "VisibilityTimeoutSeconds": 30 }'
The response contains the queue description, including the generated queue ARN and the
queue status. The queue starts in the CREATING state:
{ "QueueDescription": { "QueueName": "my-queue", "QueueARN": "arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "QueueStatus": "CREATING", "QueueCreationTimestamp": "2026-01-15T10:30:00Z", "StreamConfigurationList": [ { "StreamARN": "arn:aws:kinesis:us-west-2:111122223333:stream/my-stream", "StartingPosition": { "Type": "TRIM_HORIZON" } } ], "QueueAttributes": { "VisibilityTimeoutSeconds": 30, "DeadLetterConfiguration": { "TargetType": "BUILT_IN", "MaxReceiveCount": 6 } } } }
The queue ARN resource id is generated when you create the queue. It is not derived from the queue name. Use this queue ARN in the commands that follow.
If you omit VisibilityTimeoutSeconds, the queue uses the service
default visibility timeout of 30 seconds. Dead-letter handling is enabled by default, so
DeadLetterConfiguration appears in the queue description with a
MaxReceiveCount of 6 even when you do not specify it.
Step 3: Wait for the queue to become active
Creating a queue is asynchronous. Call describe-queue with the queue ARN
and wait until QueueStatus is ACTIVE before you receive
records:
aws kinesis describe-queue \ --queue-arn arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
{ "QueueDescription": { "QueueName": "my-queue", "QueueARN": "arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "QueueStatus": "ACTIVE", "QueueCreationTimestamp": "2026-01-15T10:30:00Z", "StreamConfigurationList": [ { "StreamARN": "arn:aws:kinesis:us-west-2:111122223333:stream/my-stream", "StartingPosition": { "Type": "TRIM_HORIZON", "Timestamp": "2026-01-15T10:29:36Z" } } ], "QueueAttributes": { "VisibilityTimeoutSeconds": 30, "DeadLetterConfiguration": { "TargetType": "BUILT_IN", "MaxReceiveCount": 6 } } } }
Step 4: List the queues on a stream
To find the queues on a stream, call list-queues with a
StreamFilter entry for that stream:
aws kinesis list-queues \ --stream-filter '[ { "StreamARN": "arn:aws:kinesis:us-west-2:111122223333:stream/my-stream" } ]'
{ "QueueSummaries": [ { "QueueName": "my-queue", "QueueARN": "arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "QueueStatus": "ACTIVE", "QueueCreationTimestamp": "2026-01-15T10:30:00Z", "Streams": [ { "StreamARN": "arn:aws:kinesis:us-west-2:111122223333:stream/my-stream", "StreamCreationTimestamp": "2026-01-15T10:29:36Z" } ] } ] }
Step 5: Receive records
Receive records with receive-queue-records. Set --limit to
the number of records to return (1 to 10). Set --wait-time-seconds to how
long the call waits for records to arrive, from 1 to 20 seconds. If you omit it, the
call waits 9 seconds:
aws kinesis receive-queue-records \ --queue-arn arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \ --limit 10 \ --wait-time-seconds 20
Each returned record carries a receipt handle and delivery metadata in addition to the data and partition key. The record data is base64 encoded:
{ "QueueRecords": [ { "ReceiptHandle": "AQEBxyzReceiptHandleEXAMPLE1111==", "RecordId": "2c455db5cc0161eb3dbac00da1ce9337", "PartitionKey": "user-1", "Data": "aGVsbG8gd29ybGQ=", "ApproximateArrivalTimestamp": "2026-01-15T10:29:40.123456+00:00", "FirstReceiveTimestamp": "2026-01-15T10:31:05.654321+00:00", "ReceiveCount": 1 } ] }
Use the ReceiptHandle value to acknowledge a record, change its visibility
timeout, or restore it. A new receipt handle is issued each time you receive a record.
The RecordId value identifies the record and stays the same across its
deliveries.
While a record is in flight, it is not visible to any queue consumer instance until the record is acknowledged or its visibility timeout expires. If the timeout expires without an acknowledgment, the record becomes visible again and the queue can deliver it to any consumer instance.
Step 6: Extend the visibility timeout of a record
If you need more time to process a record, extend its visibility timeout with
update-queue-records-visibility. Each entry carries a
ReceiptHandle and a VisibilityTimeoutSeconds value. There is
no caller-supplied id:
aws kinesis update-queue-records-visibility \ --queue-arn arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \ --entries '[ { "ReceiptHandle": "AQEBxyzReceiptHandleEXAMPLE1111==", "VisibilityTimeoutSeconds": 60 } ]'
Results are returned in the Successful and Failed lists,
correlated by ReceiptHandle:
{ "Successful": [ { "ReceiptHandle": "AQEBxyzReceiptHandleEXAMPLE1111==" } ], "Failed": [] }
To make a record visible immediately, set its
VisibilityTimeoutSeconds to 0.
Step 7: Change the queue default visibility timeout
To change the default visibility timeout for every record the queue delivers, call
update-queue with the new value in QueueAttributes:
aws kinesis update-queue \ --queue-arn arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \ --queue-attributes '{ "VisibilityTimeoutSeconds": 60 }'
UpdateQueue changes the queue attributes: the default visibility timeout
and the dead-letter configuration. The stream association, the queue name, and the
starting position cannot be updated.
Updating a queue is asynchronous. The queue status moves to UPDATING and
returns to ACTIVE when the change is applied.
Step 8: Acknowledge records
A queue consumer acknowledges the records it successfully processes, up to 10 per
call. Call
acknowledge-queue-records with one entry per record. Each entry carries a
ReceiptHandle and nothing else. There is no caller-supplied id:
aws kinesis acknowledge-queue-records \ --queue-arn arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \ --entries '[ { "ReceiptHandle": "AQEBxyzReceiptHandleEXAMPLE1111==" } ]'
Results are returned in the Successful and Failed lists,
correlated by ReceiptHandle:
{ "Successful": [ { "ReceiptHandle": "AQEBxyzReceiptHandleEXAMPLE1111==" } ], "Failed": [] }
Because an individual record can fail to be acknowledged even when the call returns
HTTP 200, check the Failed list on every response and retry the entries it
contains.
Acknowledging a record affects only the queue. The underlying stream record stays for its retention period and remains readable by stream consumers and by any other queue on the same stream.
Step 9: Clean up
To avoid ongoing charges, delete the resources you created when you no longer need
them. For pricing details, see
Amazon Kinesis Data Streams
pricing
Delete the queue:
aws kinesis delete-queue \ --queue-arn arn:aws:kinesis:us-west-2:111122223333:queue/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
Deleting a queue is asynchronous and does not delete the stream or its records. You
must delete every queue on a stream before you can delete the stream or switch it from
On-demand to provisioned capacity mode. DeleteStream fails with
ResourceInUseException while a queue is attached, and
EnforceConsumerDeletion has no effect on queues.
After the queue is deleted, delete the stream:
aws kinesis delete-stream \ --stream-name my-stream