# Peek Messages (/sdks/nodejs/how-to/queues/peek-messages)



## Overview [#overview]

Peeking lets you look at what's sitting in a queue without touching it — the messages stay exactly where they are, still waiting for whichever consumer eventually receives them. It's the tool you reach for when you need visibility into queue state — checking backlog depth, inspecting payloads while debugging a stuck pipeline, or building an operational dashboard — without risking a collision with real consumers competing for the same work.

`peekQueueMessages()` is a variant of the same call `receiveQueueMessages()` uses, just in read-only mode: it takes the same `channel`, `maxMessages`, and `waitTimeoutSeconds`, but the broker never marks the returned messages as delivered, locks them, or starts a visibility timeout — so no acknowledgment is needed or even possible.

**Gotchas:** peeked messages aren't reserved for you — a consumer can `receiveQueueMessages()` and remove them the instant after you peek, so treat the count as a point-in-time estimate, not a guarantee. Peek also won't surface messages already locked inside another consumer's in-flight receive, and it's not a substitute for receiving when you actually intend to process what you see.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* Node.js SDK installed (`npm install kubemq-js`)

## Code [#code]

```typescript title="peek-messages.ts"
/**
 * Example: Peek (Waiting) Messages Without Consuming
 *
 * Demonstrates peeking at messages in a queue without removing them.
 * Useful for monitoring queue depth or inspecting messages before
 * deciding whether to process them.
 *
 * Prerequisites:
 *   - KubeMQ server running on localhost:50000
 *
 * Run: npx tsx examples/queues/peek-messages.ts
 */
import { KubeMQClient, createQueueMessage } from 'kubemq-js';

async function main(): Promise<void> {
  const client = await KubeMQClient.create({
    address: 'localhost:50000',
    clientId: 'js-queues-peek-messages-client',
  });

  try {
    // Send a few messages to inspect.
    for (let i = 1; i <= 3; i++) {
      await client.sendQueueMessage(
        createQueueMessage({
          channel: 'js-queues.peek-messages',
          body: `Report #${i} ready for review`,
        }),
      );
    }

    // Peek at waiting messages — they remain in the queue.
    const peeked = await client.peekQueueMessages({
      channel: 'js-queues.peek-messages',
      waitTimeoutSeconds: 5,
      maxMessages: 10,
    });

    console.log(`Found ${peeked.length} messages waiting:`);
    for (const msg of peeked) {
      console.log(`  - ${new TextDecoder().decode(msg.body)}`);
    }
  } finally {
    await client.close();
  }
}

main().catch(console.error);

```

## How It Works [#how-it-works]

* `peekQueueMessages()` is a non-destructive read: messages are inspected but not locked or removed — the queue state is unchanged after the call.
* Unlike `receiveQueueMessages()`, no acknowledgment is required because peek does not lock the messages; other consumers can still receive them.
* `waitTimeoutSeconds: 5` and `maxMessages: 10` work the same as in receive — the call returns early if messages are available before the timeout.
* Use peek for monitoring queue depth, debugging message content, or inspecting headers before committing to processing a batch.

## Related [#related]

* [Pattern overview](/learn/queues/getting-started)
* [Node.js SDK Reference](/sdks/nodejs/reference)
* [Send & Receive](/sdks/nodejs/tutorials/send-receive)
* [Ack All](/sdks/nodejs/how-to/queues/ack-all)