# list_queued_messages

Source: https://modulify.ai/docs/api/chat/list-queued-messages

Reads the messages waiting to run on a site, oldest first, from the same queue everyone in the workspace sees.

- Title: Read the message queue
- Scope: `chat:read`
- Access: Read only
- Endpoint: `POST /v1/list_queued_messages`

A message lands here when `send_message` is called while the site agent is busy, or while the queue is parked after a run that was stopped, failed or ended part way through. Each entry carries its `Id`, its `Content`, the mode it runs in as `QueueMode`, its author in `UserId` and `UserName`, and the `QueueVersion` that `edit_queued_message` requires.

An edit is refused when the version it sends is not the current one, so the tool tells the client to read the queue before editing or removing anything, and to read it again after a rejection. See [Message queue](https://modulify.ai/docs/build/message-queue#read-the-queue).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/list_queued_messages`, sending the inputs below as a JSON object. The token needs the `chat:read` scope.

It only reads and changes nothing, so retrying it is safe.

```bash
curl -X POST https://api.modulify.ai/v1/list_queued_messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID"}'
```

Over MCP, the same method is the [list_queued_messages tool](https://modulify.ai/docs/mcp/chat/list-queued-messages).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id, from `list_sites` or `get_site`. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.