Skip to content 
Steps
List Steps
Retrieve Step
ModelsExpand Collapse
ProviderTrace object { request_json, response_json, id, 15 more }
Letta’s internal representation of a provider trace.
Attributes: id (str): The unique identifier of the provider trace. request_json (Dict[str, Any]): JSON content of the provider request. response_json (Dict[str, Any]): JSON content of the provider response. step_id (str): ID of the step that this trace is associated with. agent_id (str): ID of the agent that generated this trace. agent_tags (list[str]): Tags associated with the agent for filtering. call_type (str): Type of call (agent_step, summarization, etc.). run_id (str): ID of the run this trace is associated with. source (str): Source service that generated this trace (memgpt-server, lettuce-py). organization_id (str): The unique identifier of the organization. user_id (str): The unique identifier of the user who initiated the request. compaction_settings (Dict[str, Any]): Compaction/summarization settings (only for summarization calls). llm_config (Dict[str, Any]): LLM configuration used for this call (only for non-summarization calls). created_at (datetime): The timestamp when the object was created.
Step object { id, agent_id, cache_write_tokens, 27 more }
cache_write_tokens: optional number
The number of input tokens written to cache (Anthropic only). None if not reported by provider.
cached_input_tokens: optional number
The number of input tokens served from cache. None if not reported by provider.
completion_tokens_details: optional map[unknown]
Detailed completion token breakdown (e.g., reasoning_tokens).
The messages generated during this step. Deprecated: use GET /v1/steps/{step_id}/messages endpoint instead
approval_request_id: optional string
The id of the approval request if this message is associated with a tool call request.
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or object { status, func_response, stderr, 2 more }
The list of approvals for this message.
LettaSchemasMessageToolReturnOutput object { status, func_response, stderr, 2 more }
func_response: optional string or array of TextContent { text, signature, type } or ImageContent { source, type }
The function response - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
content: optional array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
The content of the message.
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ToolCallContent object { id, input, name, 2 more }
ReasoningContent object { is_native, reasoning, signature, type }
is_err: optional boolean
Whether this message is part of an error step. Used only for debugging purposes.
name: optional string
For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.
tool_returns: optional array of object { status, func_response, stderr, 2 more }
Tool execution return information for prior tool calls
func_response: optional string or array of TextContent { text, signature, type } or ImageContent { source, type }
The function response - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
project_id: optional string
The project that the agent that executed this step belongs to (cloud only).
prompt_tokens_details: optional map[unknown]
Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens, cache_creation_tokens).
reasoning_tokens: optional number
The number of reasoning/thinking tokens generated. None if not reported by provider.
request_id: optional string
The API request log ID from cloud-api for correlating steps with API requests.
run_id: optional string
The unique identifier of the run that this step belongs to. Only included for async calls.
StepsMetrics
Retrieve Metrics For Step
StepsTrace
Retrieve Trace For Step
StepsFeedback
Modify Feedback For Step
StepsMessages
List Messages For Step
ModelsExpand Collapse
MessageListResponse = SystemMessage { id, content, date, 8 more } or UserMessage { id, content, date, 8 more } or ReasoningMessage { id, date, reasoning, 10 more } or 8 more
A message generated by the system. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system
SystemMessage object { id, content, date, 8 more }
A message generated by the system. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system
UserMessage object { id, content, date, 8 more }
A message sent by the user. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)
The message content sent by the user (can be a string or an array of multi-modal content parts)
array of LettaUserMessageContentUnion
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ReasoningMessage object { id, date, reasoning, 10 more }
Representation of an agent’s internal reasoning.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal[“reasoner_model”, “non_reasoner_model”]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step
otid: optional string
The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.
HiddenReasoningMessage object { id, date, state, 9 more }
Representation of an agent’s internal reasoning where reasoning content has been hidden from the response.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal[“redacted”, “omitted”]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent
ToolCallMessage object { id, date, tool_call, 9 more }
A message representing a request to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
otid: optional string
The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
array of ToolCall { arguments, name, tool_call_id }
ToolReturnMessage object { id, date, status, 13 more }
A message representing the return value of a tool call (generated by Letta executing the requested tool).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal[“success”, “error”]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support
otid: optional string
The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.
tool_return: array of TextContent { text, signature, type } or ImageContent { source, type } or string
The tool return value - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
AssistantMessage object { id, content, date, 8 more }
A message sent by the LLM in response to user input. Used in the LLM context.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)
The message content sent by the agent (can be a string or an array of content parts)
array of LettaAssistantMessageContentUnion { text, signature, type }
ApprovalRequestMessage object { id, date, tool_call, 9 more }
A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool call that has been requested by the llm to run
otid: optional string
The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool calls that have been requested by the llm to run, which are pending approval
array of ToolCall { arguments, name, tool_call_id }
ApprovalResponseMessage object { id, date, approval_request_id, 11 more }
A message representing a response form the user indicating whether a tool has been approved to run.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ToolReturn object { status, tool_call_id, tool_return, 3 more }
tool_return: array of TextContent { text, signature, type } or ImageContent { source, type } or string
The tool return value - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
SummaryMessage object { id, date, summary, 9 more }
A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.
compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }
EventMessage object { id, date, event_data, 9 more }
A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.