Get number of messages in an Amazon SQS Queue

Get number of messages in an Amazon SQS Queue

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Get number of messages in an Amazon SQS Queue

Determining the current backlog of a queue is a fundamental operation for monitoring system health, triggering scaling events, or debugging processing bottlenecks. In AWS Simple Queue Service (SQS), this metric is not stored as a dynamic counter that you retrieve by polling; rather, it is an attribute exposed directly by the queue metadata. The API provides a straightforward way to access this count without needing to iterate through individual messages or perform expensive list operations.

To retrieve the number of messages waiting in a specific SQS queue using the AWS SDK for PHP, you instantiate an Sqs client and call the getQueueAttributes method. This operation returns a collection of attributes associated with the queue, one of which is ApproximateNumberOfMessages. Unlike the ReceiveMessage action, which has a default message visibility timeout and limits how many messages you can fetch per request (typically 10), querying the attribute is asynchronous in nature regarding data freshness but synchronous in execution.

<?php

require 'vendor/autoload.php';

use Aws\Sqs\SqsClient;

$sqs = new SqsClient([
    'region' => 'us-east-1',
    'version' => 'latest'
]);

$queueUrl = 'https://sqs.us-east-1.amazonaws.com/123456789012/my-queue';

// Retrieve all attributes for the queue
$result = $sqs->getQueueAttributes([
    'QueueUrl' => $queueUrl,
    'AttributeNames' => ['ApproximateNumberOfMessages']
]);

$attributes = $result['Attributes'];

if (isset($attributes['ApproximateNumberOfMessages'])) {
    $messageCount = (int) $attributes['ApproximateNumberOfMessages'];
    
    // Handle the case where no messages are present
    if ($messageCount === '0') {
        echo "The queue is currently empty.\n";
    } else {
        echo "Current message count: {$messageCount}\n";
    }
} else {
    echo "Failed to retrieve attribute.\n";
}

?>

When using cURL directly against the AWS API, the logic remains identical but requires constructing a JSON payload that mirrors the SDK's input parameters. You must include the Action set to GetQueueAttributes and specify the exact list of attributes you need in the AttributeNames parameter. If you omit this parameter or leave it empty, the response will only contain the default attributes like ApproximateNumberOfMessagesVisible, which might differ from your internal logic if you are managing message visibility timeouts manually.

curl --location 'https://sqs.us-east-1.amazonaws.com/123456789012/my-queue' \
--header 'Authorization: AWS Signature Version 4 (calculated)' \
--data '{
    "Action": "GetQueueAttributes",
    "AttributeName.1": "ApproximateNumberOfMessages"
}'

Note: The cURL example above shows the payload structure. In a real-world scenario, you must generate a valid AWS Signature Version 4 header using your access key and secret key, or use aws configure to set up environment variables for signing.

A critical detail developers often overlook is the distinction between ApproximateNumberOfMessages and ApproximateNumberOfMessagesVisible. The former includes messages that have not yet expired but might be invisible due to a visibility timeout. The latter only counts messages currently available for immediate consumption by consumers. If your application frequently reads messages without deleting them, or if you rely heavily on long visibility timeouts, relying solely on the generic count can lead to inflated metrics regarding actual processing load.

Another consideration is the latency of this data. SQS does not provide real-time exact counts. The value returned is approximate and cached internally by AWS to optimize performance. While this is rarely a problem for high-level monitoring dashboards, it means you cannot use this metric for precise inventory control if every message must be accounted for instantly.

For Laravel projects specifically, the facade/aws package or the dedicated aws-php-sdk-v3 allows you to integrate this logic seamlessly into your existing queue workers or artisan commands. If you are managing high-volume queues where the approximate count is insufficient, you might consider implementing a custom metric in your database or using CloudWatch to log the attribute every few seconds for trend analysis.

Our network