---
title: "Send Message Async"
method: POST
path: "/v1/agents/{agent_id}/messages/async"
tags: ["agents"]
---

# Send Message Async

`POST /v1/agents/{agent_id}/messages/async`

Asynchronously process a user message and return a run object.
The actual processing happens in the background, and the status can be checked using the run ID.

This is "asynchronous" in the sense that it's a background run and explicitly must be fetched by the run ID.

## Path parameters

- `agent_id` string, required

## Request body

- LettaAsyncRequest
  - `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[]
            - union
              - …
          - 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.
  - `callback_url` string, nullable — Optional callback URL to POST to when the job completes

## Response `200`

Successful Response

- Run — Representation of a run - a conversation or processing session for an agent. Runs track when agents process messages and maintain the relationship between agents, steps, and messages. Parameters: id (str): The unique identifier of the run (prefixed with 'run-'). status (JobStatus): The current status of the run. created_at (datetime): The timestamp when the run was created. completed_at (datetime): The timestamp when the run was completed. agent_id (str): The unique identifier of the agent associated with the run. stop_reason (StopReasonType): The reason why the run was stopped. background (bool): Whether the run was created in background mode. metadata (dict): Additional metadata for the run. request_config (LettaRequestConfig): The request configuration for the run.
  - `id` string — The human-friendly ID of the Run
  - `status` 'created' | 'running' | 'completed' | 'failed' | 'cancelled' — Status of the run.
  - `created_at` string, date-time — The timestamp when the run was created.
  - `completed_at` string, date-time, nullable — The timestamp when the run was completed.
  - `agent_id` string, required — The unique identifier of the agent associated with the run.
  - `background` boolean, nullable — Whether the run was created in background mode.
  - `metadata` object, nullable — Additional metadata for the run.
  - `request_config` LettaRequestConfig
    - `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.
  - `stop_reason` 'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'
  - `callback_url` string, nullable — If set, POST to this URL when the run completes.
  - `callback_sent_at` string, date-time, nullable — Timestamp when the callback was last attempted.
  - `callback_status_code` integer, nullable — HTTP status code returned by the callback endpoint.
  - `callback_error` string, nullable — Optional error message from attempting to POST the callback endpoint.
  - `ttft_ns` integer, nullable — Time to first token for a run in nanoseconds
  - `total_duration_ns` integer, nullable — Total run duration in nanoseconds

## 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)