cloudflare · mia303 · Apr 10, 2026 · Apr 10, 2026 · Apr 14, 2026 · Apr 14, 2026
@@ -0,0 +1,35 @@
+---
+title: Realtime backlog metrics now available for Queues
+description: Cloudflare Queues metrics now include realtime backlog size (in count & bytes) and oldest message timestamp
+products:
+  - queues
+date: 2026-04-15
+---
+
+[Queues](/queues/), Cloudflare's managed message queue, now exposes realtime backlog metrics via the dashboard, REST API, and JavaScript API. Three new fields are available:
+
+- **`backlog_count`** — the number of unacknowledged messages in the queue
+- **`backlog_bytes`** — the total size of those messages in bytes
+- **`oldest_message_timestamp_ms`** — the timestamp of the oldest unacknowledged message
+
+The following endpoints also now include a `metadata.metrics` object on the result field after successful message consumption:
+
+- `/accounts/{account_id}/queues/{queue_id}/messages/pull`
+- `/accounts/{account_id}/queues/{queue_id}/messages`
+- `/accounts/{account_id}/queues/{queue_id}/messages/batch`
+
+### Javascript APIs
+
+Call `env.QUEUE.metrics()` to get realtime backlog metrics:
+
+```ts
+const {
+  backlogCount,                // number
+  backlogBytes,                // number
+  oldestMessageTimestamp,      // Date | undefined
+} = await env.QUEUE.metrics()
+```
+
+`env.QUEUE.send()` and `env.QUEUE.sendBatch()` also now return a metrics object on the response.
+
+You can also query these fields via the [GraphQL Analytics API](/analytics/graphql-api/). For more information, refer to [Metrics](/queues/observability/metrics/).
@@ -92,24 +92,29 @@ A binding that allows a producer to send messages to a Queue.
 
 ```ts
 interface Queue<Body = unknown> {
-  send(body: Body, options?: QueueSendOptions): Promise<void>;
-  sendBatch(messages: Iterable<MessageSendRequest<Body>>, options?: QueueSendBatchOptions): Promise<void>;
+  send(body: Body, options?: QueueSendOptions): Promise<QueueSendResult>;
+  sendBatch(messages: Iterable<MessageSendRequest<Body>>, options?: QueueSendBatchOptions): Promise<QueueSendResult>;
+  metrics(): Promise<QueueMetrics>;
 }
 ```
 
 
 
-* `send(bodyunknown, options?{ contentType?: QueuesContentType })` <Type text="Promise<void>" />
+* `send(body: unknown, options?: {contentType?: QueuesContentType })` <Type text="Promise<QueueSendResult>" />
 
   * Sends a message to the Queue. The body can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types), as long as its size is less than 128 KB.
   * When the promise resolves, the message is confirmed to be written to disk.
+  * Returns a [QueueSendResult](#queuesendresult) containing realtime metrics about the queue.
 
-* `sendBatch(messagesIterable<MessageSendRequest<unknown>>, options?QueueSendBatchOptions)` <Type text="Promise<void>" />
+* `sendBatch(messages: Iterable<MessageSendRequest<unknown>>, options?: QueueSendBatchOptions)` <Type text="Promise<QueueSendBatchResult>" />
 
   * Sends a batch of messages to the Queue. Each item in the provided [Iterable](https://www.typescriptlang.org/docs/handbook/iterators-and-generators.html) must be supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). A batch can contain up to 100 messages, though items are limited to 128 KB each, and the total size of the array cannot exceed 256 KB.
   * The optional `options` parameter can be used to apply settings (such as `delaySeconds`) to all messages in the batch. See [QueueSendBatchOptions](#queuesendbatchoptions).
   * When the promise resolves, the messages are confirmed to be written to disk.
 
+* `metrics()` <Type text="Promise<QueueMetrics>" />
+
+  * Returns realtime [QueueMetrics](#queuemetrics) for the queue.
 
 
 ### `MessageSendRequest`
@@ -191,6 +196,54 @@ The default content type for Queues changed to `json` (from `v8`) to improve com
 
 If you specify an invalid content type, or if your specified content type does not match the message content's type, the send operation will fail with an error.
 
+### `QueueSendResult`
+
+The result of a successful send operation.
+
+```ts
+interface QueueSendResult {
+	metadata: {
+		metrics: QueueMetrics;
+	};
+}
+```
+
+
+
+* <code>metadata</code> <Type text="object" />
+
+  * Contains metadata about the queue after the send operation.
+
+* <code>metadata.metrics</code> <Type text="QueueMetrics" />
+
+  * Realtime metrics for the queue. See [QueueMetrics](#queuemetrics).
+
+### `QueueMetrics`
+
+Realtime metrics for a queue.
+
+```ts
+interface QueueMetrics {
+	backlogCount: number;
+	backlogBytes: number;
+	oldestMessageTimestamp: number;
+}
+```
+
+
+
+* <code>backlogCount</code> <Type text="number" />
+
+  * The number of messages currently in the queue.
+
+* <code>backlogBytes</code> <Type text="number" />
+
+  * The total size of messages in the queue, in bytes.
+
+* <code>oldestMessageTimestamp</code> <Type text="number" />
+
+  * The timestamp (in milliseconds since epoch) of the oldest message in the queue.
+
 ## Consumer
 
 These APIs allow a consumer Worker to consume messages from a Queue.
@@ -355,3 +408,5 @@ interface QueueRetryOptions {
 
   * The number of seconds to [delay a message](/queues/configuration/batching-retries/) for within the queue, before it can be delivered to a consumer.
   * Must be a positive integer.
+* When the promise resolves, the messages are confirmed to be written to disk.
+  * Returns a [QueueSendResult](#queuesendresult) containing realtime metrics about the queue.
@@ -67,6 +67,20 @@ The `queueMessageOperationsAdaptiveGroups` dataset provides the following dimens
 - `datetimeHour` - Timestamp for the message operation, truncated to the start of an hour
 - `datetimeMinute` - Timestamp for the message operation, truncated to the start of a minute
 
+### Realtime backlog
+
+You can access realtime backlog metrics via the [Queues REST API](/api/resources/queues/) and [JavaScript API](/queues/configuration/javascript-apis/). These metrics provide point-in-time values rather than aggregated data.
+
+| Metric                   | Field Name                 | Description                                                    |
+| ------------------------ | -------------------------- | -------------------------------------------------------------- |
+| Backlog count            | `backlog_count`            | Number of messages currently in the queue                      |
+| Backlog bytes            | `backlog_bytes`            | Total size of messages in the queue, in bytes                  |
+| Oldest message timestamp | `oldest_message_timestamp_ms` | Timestamp (in milliseconds) of the oldest message in the queue |
+
+To retrieve these metrics via the REST API, use the metrics endpoint (`/accounts/{account_id}/queues/{queue_id}/metrics`).
+
+These fields are also included in `metadata.metrics` when calling `send()`, `sendBatch()`, or `metrics()` via the JavaScript API.
+
 ## Example GraphQL Queries
 
 ### Get average queue backlog over time period