Steps
List Steps
Retrieve Step
ModelsExpand Collapse
ProviderTrace { request_json, response_json, id, 5 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. organization_id (str): The unique identifier of the organization. created_at (datetime): The timestamp when the object was created.
request_json: Record<string, unknown>
JSON content of the provider request
response_json: Record<string, unknown>
JSON content of the provider response
id?: string
The human-friendly ID of the Provider_trace
created_at?: string
The timestamp when the object was created.
created_by_id?: string | null
The id of the user that made this object.
last_updated_by_id?: string | null
The id of the user that made this object.
step_id?: string | null
ID of the step that this trace is associated with
updated_at?: string | null
The timestamp when the object was last updated.
Step { id, agent_id, completion_tokens, 21 more }
id: string
The id of the step. Assigned by the database.
agent_id?: string | null
The ID of the agent that performed the step.
completion_tokens?: number | null
The number of tokens generated by the agent during this step.
completion_tokens_details?: Record<string, unknown> | null
Metadata for the agent.
context_window_limit?: number | null
The context window limit configured for this step.
error_data?: Record<string, unknown> | null
Error details including message, traceback, and additional context
error_type?: string | null
The type/class of the error that occurred
feedback?: "positive" | "negative" | null
The feedback for this step. Must be either 'positive' or 'negative'.
The messages generated during this step. Deprecated: use GET /v1/steps/{step_id}/messages endpoint instead
id: string
The human-friendly ID of the Message
The role of the participant.
agent_id?: string | null
The unique identifier of the agent.
approval_request_id?: string | null
The id of the approval request if this message is associated with a tool call request.
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | LettaSchemasMessageToolReturn { status, func_response, stderr, 2 more } > | null
The list of approvals for this message.
ApprovalReturn { approve, tool_call_id, reason, type }
approve: boolean
Whether the tool has been approved
tool_call_id: string
The ID of the tool call that corresponds to this approval
reason?: string | null
An optional explanation for the provided approval status
type?: "approval"
The message type to be created.
LettaSchemasMessageToolReturn { status, func_response, stderr, 2 more }
status: "success" | "error"
The status of the tool call
func_response?: string | null
The function response string
stderr?: Array<string> | null
Captured stderr from the tool invocation
stdout?: Array<string> | null
Captured stdout (e.g. prints, logs) from the tool invocation
tool_call_id?: unknown
The ID for the tool call
approve?: boolean | null
Whether tool call is approved.
batch_item_id?: string | null
The id of the LLMBatchItem that this message is associated with
content?: Array<TextContent { text, signature, type } | ImageContent { source, type } | ToolCallContent { id, input, name, 2 more } | 5 more> | null
The content of the message.
TextContent { text, signature, type }
text: string
The text content of the message.
signature?: string | null
Stores a unique identifier for any reasoning associated with this text content.
type?: "text"
The type of the message.
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
The source of the image.
URLImage { url, type }
url: string
The URL of the image.
type?: "url"
The source type for the image.
Base64Image { data, media_type, detail, type }
data: string
The base64 encoded image data.
media_type: string
The media type for the image.
detail?: string | null
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type?: "base64"
The source type for the image.
LettaImage { file_id, data, detail, 2 more }
file_id: string
The unique identifier of the image file persisted in storage.
data?: string | null
The base64 encoded image data.
detail?: string | null
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type?: string | null
The media type for the image.
type?: "letta"
The source type for the image.
type?: "image"
The type of the message.
ToolCallContent { id, input, name, 2 more }
id: string
A unique identifier for this specific tool call instance.
input: Record<string, unknown>
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: string
The name of the tool being called.
signature?: string | null
Stores a unique identifier for any reasoning associated with this tool call.
type?: "tool_call"
Indicates this content represents a tool call event.
ToolReturnContent { content, is_error, tool_call_id, type }
content: string
The content returned by the tool execution.
is_error: boolean
Indicates whether the tool execution resulted in an error.
tool_call_id: string
References the ID of the ToolCallContent that initiated this tool call.
type?: "tool_return"
Indicates this content represents a tool return event.
ReasoningContent { is_native, reasoning, signature, type }
Sent via the Anthropic Messages API
is_native: boolean
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: string
The intermediate reasoning or thought process content.
signature?: string | null
A unique identifier for this reasoning step.
type?: "reasoning"
Indicates this is a reasoning/intermediate step.
RedactedReasoningContent { data, type }
Sent via the Anthropic Messages API
data: string
The redacted or filtered intermediate reasoning content.
type?: "redacted_reasoning"
Indicates this is a redacted thinking step.
OmittedReasoningContent { signature, type }
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature?: string | null
A unique identifier for this reasoning step.
type?: "omitted_reasoning"
Indicates this is an omitted reasoning step.
SummarizedReasoningContent { id, summary, encrypted_content, type }
The style of reasoning content returned by the OpenAI Responses API
id: string
The unique identifier for this reasoning step.
summary: Array<Summary>
Summaries of the reasoning content.
index: number
The index of the summary part.
text: string
The text of the summary part.
encrypted_content?: string
The encrypted reasoning content.
type?: "summarized_reasoning"
Indicates this is a summarized reasoning step.
created_at?: string
The timestamp when the object was created.
created_by_id?: string | null
The id of the user that made this object.
denial_reason?: string | null
The reason the tool call request was denied.
group_id?: string | null
The multi-agent group that the message was sent in
is_err?: boolean | null
Whether this message is part of an error step. Used only for debugging purposes.
last_updated_by_id?: string | null
The id of the user that made this object.
model?: string | null
The model used to make the function call.
name?: string | null
For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.
otid?: string | null
The offline threading id associated with this message
run_id?: string | null
The id of the run that this message was created in.
sender_id?: string | null
The id of the sender of the message, can be an identity id or agent id
step_id?: string | null
The id of the step that this message was created in.
tool_call_id?: string | null
The ID of the tool call. Only applicable for role tool.
tool_calls?: Array<ToolCall> | null
The list of tool calls requested. Only applicable for role assistant.
function: Function { arguments, name }
type: "function"
tool_returns?: Array<ToolReturn> | null
Tool execution return information for prior tool calls
status: "success" | "error"
The status of the tool call
func_response?: string | null
The function response string
stderr?: Array<string> | null
Captured stderr from the tool invocation
stdout?: Array<string> | null
Captured stdout (e.g. prints, logs) from the tool invocation
tool_call_id?: unknown
The ID for the tool call
updated_at?: string | null
The timestamp when the object was last updated.
model?: string | null
The name of the model used for this step.
model_endpoint?: string | null
The model endpoint url used for this step.
origin?: string | null
The surface that this agent step was initiated from.
project_id?: string | null
The project that the agent that executed this step belongs to (cloud only).
prompt_tokens?: number | null
The number of tokens in the prompt during this step.
provider_category?: string | null
The category of the provider used for this step.
provider_id?: string | null
The unique identifier of the provider that was configured for this step
provider_name?: string | null
The name of the provider used for this step.
run_id?: string | null
The unique identifier of the run that this step belongs to. Only included for async calls.
status?: "pending" | "success" | "failed" | "cancelled" | null
Status of a step execution
The stop reason associated with the step.
tags?: Array<string>
Metadata tags.
tid?: string | null
The unique identifier of the transaction that processed this step.
total_tokens?: number | null
The total number of tokens processed by the agent during this step.
trace_id?: string | null
The trace id of the agent step.