---
title: "Queue Session Message"
method: POST
path: "/sessions/{session_id}/queue"
tags: ["Sessions"]
---

# Queue Session Message

`POST /sessions/{session_id}/queue`

## Request

- Base URL: `https://api.browser-use.com/api/v4`
- URL: `https://api.browser-use.com/api/v4/sessions/{session_id}/queue`
- Auth: API key in header `X-Browser-Use-API-Key`

Send a message to a session. If the session is busy it waits on the queue
and runs as the next turn; if idle it drains immediately.

`interrupt=true` cancels the session's active run so this message takes effect
now instead of waiting for the current turn (no-op when the session is idle).

## Path parameters

- `session_id` string, uuid, required

## Headers

- `X-V4-Queue-Deduplicate` string, nullable

## Request body

- QueueMessageRequest: Send a message to a session. If the session is busy the message waits on the queue and runs as the next turn; if idle it runs immediately. Set `interrupt` to make it take effect now: the session's active run is cancelled and this message drains straight after. Interrupt is a no-op when the session is already idle, and BEST-EFFORT when busy — if the cancel can't be delivered, the message stays queued and runs after the current turn.
  - `text` string, required
  - `interrupt` boolean
  - `attachedFileIds` string[], nullable

## Response `200`

Successful Response

- QueuedMessage: One message on a session's queue (a v4_session_input row).
  - `id` integer, required
  - `sessionId` string, uuid, required
  - `runId` string, uuid, nullable, required
  - `mode` 'queue' | 'interrupt', required
  - `status` 'pending' | 'dispatching' | 'consumed' | 'cancelled' | 'superseded' | 'failed', required
  - `text` string, required
  - `attachedFileIds` string[], nullable
  - `createdAt` string, date-time, required

## Other responses

- `402`: The project has no credits available, or the authenticating API key has reached its recorded monthly total-spend soft stop.
- `403`: Zero Data Retention is enabled on the project (V4 unsupported).
- `404`: Run, session, workspace, or profile not found.
- `422`: Validation Error
- `429`: The session message queue is full.

---

[API](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4.md) · [All operations](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/llms.txt) · [OpenAPI document](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/revisions/cd7b1eee1102?raw)