---
title: "Preview Raw Payload"
method: POST
path: "/v1/agents/{agent_id}/messages/preview-raw-payload"
tags: ["agents"]
---

# Preview Raw Payload

`POST /v1/agents/{agent_id}/messages/preview-raw-payload`

Inspect the raw LLM request payload without sending it.

This endpoint processes the message through the agent loop up until
the LLM request, then returns the raw request payload that would
be sent to the LLM provider. Useful for debugging and inspection.

## Path parameters

- `agent_id` string, required

## Request body

- union
  - LettaRequest
    - `messages` union[], required — The messages to be sent to the agent.
      - union
        - MessageCreate — Request to create a message
          - `type` 'message', nullable — The message type to be created.
          - `role` 'user' | 'system' | 'assistant', required — The role of the participant.
          - `content` union, required — The content of the message.
            - LettaMessageContentUnion[]
              - …
            - string
          - `name` string, nullable — The name of the participant.
          - `otid` string, nullable — The offline threading id associated with this message
          - `sender_id` string, nullable — The id of the sender of the message, can be an identity id or agent id
          - `batch_item_id` string, nullable — The id of the LLMBatchItem that this message is associated with
          - `group_id` string, nullable — The multi-agent group that the message was sent in
        - ApprovalCreate — Input to approve or deny a tool call request
          - `type` 'approval' — The message type to be created.
          - `approve` boolean, required — Whether the tool has been approved
          - `approval_request_id` string, required — The message ID of the approval request
          - `reason` string, nullable — An optional explanation for the provided approval status
    - `max_steps` integer — Maximum number of steps the agent should take to process the request.
    - `use_assistant_message` boolean — Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects.
    - `assistant_message_tool_name` string — The name of the designated message tool.
    - `assistant_message_tool_kwarg` string — The name of the message argument in the designated message tool.
    - `include_return_message_types` MessageType[], nullable — Only return specified message types in the response. If `None` (default) returns all messages.
    - `enable_thinking` string — If set to True, enables reasoning before responses or tool calls from the agent.
  - LettaStreamingRequest
    - `messages` union[], required — The messages to be sent to the agent.
      - union
        - MessageCreate — Request to create a message
          - `type` 'message', nullable — The message type to be created.
          - `role` 'user' | 'system' | 'assistant', required — The role of the participant.
          - `content` union, required — The content of the message.
            - LettaMessageContentUnion[]
              - …
            - string
          - `name` string, nullable — The name of the participant.
          - `otid` string, nullable — The offline threading id associated with this message
          - `sender_id` string, nullable — The id of the sender of the message, can be an identity id or agent id
          - `batch_item_id` string, nullable — The id of the LLMBatchItem that this message is associated with
          - `group_id` string, nullable — The multi-agent group that the message was sent in
        - ApprovalCreate — Input to approve or deny a tool call request
          - `type` 'approval' — The message type to be created.
          - `approve` boolean, required — Whether the tool has been approved
          - `approval_request_id` string, required — The message ID of the approval request
          - `reason` string, nullable — An optional explanation for the provided approval status
    - `max_steps` integer — Maximum number of steps the agent should take to process the request.
    - `use_assistant_message` boolean — Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects.
    - `assistant_message_tool_name` string — The name of the designated message tool.
    - `assistant_message_tool_kwarg` string — The name of the message argument in the designated message tool.
    - `include_return_message_types` MessageType[], nullable — Only return specified message types in the response. If `None` (default) returns all messages.
    - `enable_thinking` string — If set to True, enables reasoning before responses or tool calls from the agent.
    - `stream_tokens` boolean — Flag to determine if individual tokens should be streamed, rather than streaming per step.
    - `include_pings` boolean — Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts.
    - `background` boolean — Whether to process the request in the background.

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.net/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yu-code666/letta-api/versions/6cec99480c13/schema)