# Peek Messages (/sdks/elixir/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.

`receive_queue_messages(client, channel, is_peek: true)` is the same call your consumers use, just with `is_peek` set to `true`: the broker returns a snapshot of messages currently queued, confirmed by the `is_peek` flag on the result, but never marks them 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 calling without `is_peek: true` can 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`
* Elixir SDK installed (`{:kubemq, "~> 1.0"}` in mix.exs)

## Code [#code]

```elixir title="main.exs"
channel = "elixir-queues.peek-messages"
{:ok, client} = KubeMQ.Client.start_link(address: "localhost:50000", client_id: "elixir-queue-peek")

for i <- 1..3 do
  {:ok, _} = KubeMQ.Client.send_queue_message(client,
    KubeMQ.QueueMessage.new(channel: channel, body: "Peekable message #{i}"))
end

IO.puts("Sent 3 messages")

case KubeMQ.Client.receive_queue_messages(client, channel,
       max_messages: 10,
       wait_timeout: 5_000,
       is_peek: true
     ) do
  {:ok, result} ->
    IO.puts("Peeked #{result.messages_received} messages (is_peek: #{result.is_peek})")

    Enum.each(result.messages, fn msg ->
      IO.puts("  #{msg.body}")
    end)

  {:error, err} ->
    IO.puts("Peek failed: #{err.message}")
end

case KubeMQ.Client.receive_queue_messages(client, channel,
       max_messages: 10,
       wait_timeout: 5_000
     ) do
  {:ok, result} ->
    IO.puts("After peek, received #{result.messages_received} messages (still available)")

  {:error, err} ->
    IO.puts("Receive failed: #{err.message}")
end

KubeMQ.Client.close(client)
```

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

* `is_peek: true` inspects messages without removing them from the queue
* Messages remain available for subsequent receive operations
* Useful for monitoring queue depth and message content

## Related [#related]

* [Send & Receive](/sdks/elixir/tutorials/send-receive)
* [Poll Mode](/sdks/elixir/how-to/queues/poll-mode)