# Runs ## List Runs **get** `/v1/runs/` List all runs. ### Query Parameters - `active: optional boolean` Filter for active runs. - `after: optional string` Cursor for pagination (run ID). Returns results relative to this ID in the specified sort order. Expected format: 'run-' - `agent_id: optional string` The unique identifier of the agent associated with the run. - `agent_ids: optional array of string` The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field. - `ascending: optional boolean` Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field. - `background: optional boolean` If True, filters for runs that were created in background mode. - `before: optional string` Cursor for pagination (run ID). Returns results relative to this ID in the specified sort order. Expected format: 'run-' - `conversation_id: optional string` Filter runs by conversation ID. - `limit: optional number` Maximum number of runs to return - `order: optional "asc" or "desc"` Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at"` Field to sort by - `"created_at"` - `statuses: optional array of string` Filter runs by status. Can specify multiple statuses. - `stop_reason: optional StopReasonType` Filter runs by stop reason. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` ### Returns - `id: string` The human-friendly ID of the Run - `agent_id: string` The unique identifier of the agent associated with the run. - `background: optional boolean` Whether the run was created in background mode. - `base_template_id: optional string` The base template ID that the run belongs to. - `callback_error: optional string` Optional error message from attempting to POST the callback endpoint. - `callback_sent_at: optional string` Timestamp when the callback was last attempted. - `callback_status_code: optional number` HTTP status code returned by the callback endpoint. - `callback_url: optional string` If set, POST to this URL when the run completes. - `completed_at: optional string` The timestamp when the run was completed. - `conversation_id: optional string` The unique identifier of the conversation associated with the run. - `created_at: optional string` The timestamp when the run was created. - `metadata: optional map[unknown]` Additional metadata for the run. - `request_config: optional object { assistant_message_tool_kwarg, assistant_message_tool_name, include_return_message_types, use_assistant_message }` The request configuration for the run. - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. - `assistant_message_tool_name: optional string` The name of the designated message tool. - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. - `status: optional "created" or "running" or "completed" or 2 more` The current status of the run. - `"created"` - `"running"` - `"completed"` - `"failed"` - `"cancelled"` - `stop_reason: optional StopReasonType` The reason why the run was stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `total_duration_ns: optional number` Total run duration in nanoseconds - `ttft_ns: optional number` Time to first token for a run in nanoseconds ### Example ```http curl https://api.letta.com/v1/runs/ \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "id": "run-123e4567-e89b-12d3-a456-426614174000", "agent_id": "agent_id", "background": true, "base_template_id": "base_template_id", "callback_error": "callback_error", "callback_sent_at": "2019-12-27T18:11:19.117Z", "callback_status_code": 0, "callback_url": "callback_url", "completed_at": "2019-12-27T18:11:19.117Z", "conversation_id": "conversation_id", "created_at": "2019-12-27T18:11:19.117Z", "metadata": { "foo": "bar" }, "request_config": { "assistant_message_tool_kwarg": "assistant_message_tool_kwarg", "assistant_message_tool_name": "assistant_message_tool_name", "include_return_message_types": [ "system_message" ], "use_assistant_message": true }, "status": "created", "stop_reason": "end_turn", "total_duration_ns": 0, "ttft_ns": 0 } ] ``` ## Retrieve Run **get** `/v1/runs/{run_id}` Get the status of a run. ### Path Parameters - `run_id: string` ### Returns - `Run object { id, agent_id, background, 14 more }` 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. - `id: string` The human-friendly ID of the Run - `agent_id: string` The unique identifier of the agent associated with the run. - `background: optional boolean` Whether the run was created in background mode. - `base_template_id: optional string` The base template ID that the run belongs to. - `callback_error: optional string` Optional error message from attempting to POST the callback endpoint. - `callback_sent_at: optional string` Timestamp when the callback was last attempted. - `callback_status_code: optional number` HTTP status code returned by the callback endpoint. - `callback_url: optional string` If set, POST to this URL when the run completes. - `completed_at: optional string` The timestamp when the run was completed. - `conversation_id: optional string` The unique identifier of the conversation associated with the run. - `created_at: optional string` The timestamp when the run was created. - `metadata: optional map[unknown]` Additional metadata for the run. - `request_config: optional object { assistant_message_tool_kwarg, assistant_message_tool_name, include_return_message_types, use_assistant_message }` The request configuration for the run. - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. - `assistant_message_tool_name: optional string` The name of the designated message tool. - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. - `status: optional "created" or "running" or "completed" or 2 more` The current status of the run. - `"created"` - `"running"` - `"completed"` - `"failed"` - `"cancelled"` - `stop_reason: optional StopReasonType` The reason why the run was stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `total_duration_ns: optional number` Total run duration in nanoseconds - `ttft_ns: optional number` Time to first token for a run in nanoseconds ### Example ```http curl https://api.letta.com/v1/runs/$RUN_ID \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "id": "run-123e4567-e89b-12d3-a456-426614174000", "agent_id": "agent_id", "background": true, "base_template_id": "base_template_id", "callback_error": "callback_error", "callback_sent_at": "2019-12-27T18:11:19.117Z", "callback_status_code": 0, "callback_url": "callback_url", "completed_at": "2019-12-27T18:11:19.117Z", "conversation_id": "conversation_id", "created_at": "2019-12-27T18:11:19.117Z", "metadata": { "foo": "bar" }, "request_config": { "assistant_message_tool_kwarg": "assistant_message_tool_kwarg", "assistant_message_tool_name": "assistant_message_tool_name", "include_return_message_types": [ "system_message" ], "use_assistant_message": true }, "status": "created", "stop_reason": "end_turn", "total_duration_ns": 0, "ttft_ns": 0 } ``` ## Domain Types ### Job - `Job object { id, agent_id, background, 15 more }` Representation of offline jobs, used for tracking status of data loading tasks (involving parsing and embedding files). - `id: optional string` The human-friendly ID of the Job - `agent_id: optional string` The agent associated with this job/run. - `background: optional boolean` Whether the job was created in background mode. - `callback_error: optional string` Optional error message from attempting to POST the callback endpoint. - `callback_sent_at: optional string` Timestamp when the callback was last attempted. - `callback_status_code: optional number` HTTP status code returned by the callback endpoint. - `callback_url: optional string` If set, POST to this URL when the job completes. - `completed_at: optional string` The unix timestamp of when the job was completed. - `created_at: optional string` The unix timestamp of when the job was created. - `created_by_id: optional string` The id of the user that made this object. - `job_type: optional JobType` The type of the job. - `"job"` - `"run"` - `"batch"` - `last_updated_by_id: optional string` The id of the user that made this object. - `metadata: optional map[unknown]` The metadata of the job. - `status: optional JobStatus` The status of the job. - `"created"` - `"running"` - `"completed"` - `"failed"` - `"pending"` - `"cancelled"` - `"expired"` - `stop_reason: optional StopReasonType` The reason why the job was stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `total_duration_ns: optional number` Total run duration in nanoseconds - `ttft_ns: optional number` Time to first token for a run in nanoseconds - `updated_at: optional string` The timestamp when the object was last updated. ### Stop Reason Type - `StopReasonType = "end_turn" or "error" or "llm_api_error" or 10 more` - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` # Messages ## List Messages For Run **get** `/v1/runs/{run_id}/messages` Get response messages associated with a run. ### Path Parameters - `run_id: string` ### Query Parameters - `after: optional string` Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-' - `before: optional string` Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-' - `limit: optional number` Maximum number of messages to return - `order: optional "asc" or "desc"` Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at"` Field to sort by - `"created_at"` ### Returns - `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 - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err: optional boolean` - `message_type: optional "system_message"` The type of the message. - `"system_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `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) - `id: string` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `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. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "user_message"` The type of the message. - `"user_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `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 - `id: string` - `date: string` - `reasoning: string` - `is_err: optional boolean` - `message_type: optional "reasoning_message"` The type of the message. - `"reasoning_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `signature: optional string` - `source: optional "reasoner_model" or "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: optional string` - `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 - `id: string` - `date: string` - `state: "redacted" or "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning: optional string` - `is_err: optional boolean` - `message_type: optional "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `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 - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "tool_call_message"` The type of the message. - `"tool_call_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { 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 - `id: string` - `date: string` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err: optional boolean` - `message_type: optional "tool_return_message"` The type of the message. - `"tool_return_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `stderr: optional array of string` - `stdout: optional array of string` - `step_id: optional string` - `tool_returns: optional array of ToolReturn` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `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) - `id: string` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the agent (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "assistant_message"` The type of the message. - `"assistant_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `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 - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `ToolCallDelta object { arguments, name, tool_call_id }` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { 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 - `id: string` - `date: string` - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { 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: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `approve: optional boolean` Whether the tool has been approved - `is_err: optional boolean` - `message_type: optional "approval_response_message"` The type of the message. - `"approval_response_message"` - `name: optional string` - `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. - `reason: optional string` An optional explanation for the provided approval status - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `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. - `id: string` - `date: string` - `summary: string` - `compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: optional number` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: optional number` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: optional boolean` - `message_type: optional "summary_message"` - `"summary_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `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. - `id: string` - `date: string` - `event_data: map[unknown]` - `event_type: "compaction"` - `"compaction"` - `is_err: optional boolean` - `message_type: optional "event_message"` - `"event_message"` - `name: optional string` - `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. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Example ```http curl https://api.letta.com/v1/runs/$RUN_ID/messages \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "id": "id", "content": "content", "date": "2019-12-27T18:11:19.117Z", "is_err": true, "message_type": "system_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id" } ] ``` ## Retrieve Stream For Run **post** `/v1/runs/{run_id}/stream` Retrieve Stream For Run ### Path Parameters - `run_id: string` ### Body Parameters - `agent_id: optional string` Agent ID for agent-direct mode with 'default' conversation. Use with conversation_id='default' in the URL path. - `batch_size: optional number` Number of entries to read per batch. - `include_pings: optional boolean` Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts. - `otid: optional string` Offline threading ID to look up the run_id. Bypasses active run lookup if run_id not provided. - `poll_interval: optional number` Seconds to wait between polls when no new data. - `run_id: optional string` Run ID to stream directly, bypassing run lookup. Use for recovery from duplicate requests. - `starting_after: optional number` Sequence id to use as a cursor for pagination. Response will start streaming after this chunk sequence id ### Example ```http curl https://api.letta.com/v1/runs/$RUN_ID/stream \ -X POST \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json {} ``` ## Domain Types ### Message Stream Response - `MessageStreamResponse = unknown` # Usage ## Retrieve Usage For Run **get** `/v1/runs/{run_id}/usage` Get usage statistics for a run. ### Path Parameters - `run_id: string` ### Returns - `completion_tokens: optional number` - `completion_tokens_details: optional object { reasoning_tokens }` - `reasoning_tokens: optional number` - `prompt_tokens: optional number` - `prompt_tokens_details: optional object { cache_creation_tokens, cache_read_tokens, cached_tokens }` - `cache_creation_tokens: optional number` - `cache_read_tokens: optional number` - `cached_tokens: optional number` - `total_tokens: optional number` ### Example ```http curl https://api.letta.com/v1/runs/$RUN_ID/usage \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "completion_tokens": 0, "completion_tokens_details": { "reasoning_tokens": 0 }, "prompt_tokens": 0, "prompt_tokens_details": { "cache_creation_tokens": 0, "cache_read_tokens": 0, "cached_tokens": 0 }, "total_tokens": 0 } ``` ## Domain Types ### Usage Retrieve Response - `UsageRetrieveResponse object { completion_tokens, completion_tokens_details, prompt_tokens, 2 more }` - `completion_tokens: optional number` - `completion_tokens_details: optional object { reasoning_tokens }` - `reasoning_tokens: optional number` - `prompt_tokens: optional number` - `prompt_tokens_details: optional object { cache_creation_tokens, cache_read_tokens, cached_tokens }` - `cache_creation_tokens: optional number` - `cache_read_tokens: optional number` - `cached_tokens: optional number` - `total_tokens: optional number` # Steps ## List Steps For Run **get** `/v1/runs/{run_id}/steps` Get steps associated with a run with filtering options. ### Path Parameters - `run_id: string` ### Query Parameters - `after: optional string` Cursor for pagination (step ID). Returns results relative to this ID in the specified sort order. Expected format: 'step-' - `before: optional string` Cursor for pagination (step ID). Returns results relative to this ID in the specified sort order. Expected format: 'step-' - `limit: optional number` Maximum number of messages to return - `order: optional "asc" or "desc"` Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at"` Field to sort by - `"created_at"` ### Returns - `id: string` The id of the step. Assigned by the database. - `agent_id: optional string` The ID of the agent that performed the step. - `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: optional number` The number of tokens generated by the agent during this step. - `completion_tokens_details: optional map[unknown]` Detailed completion token breakdown (e.g., reasoning_tokens). - `context_window_limit: optional number` The context window limit configured for this step. - `error_data: optional map[unknown]` Error details including message, traceback, and additional context - `error_type: optional string` The type/class of the error that occurred - `feedback: optional "positive" or "negative"` The feedback for this step. Must be either 'positive' or 'negative'. - `"positive"` - `"negative"` - `messages: optional array of InternalMessage` 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 - `role: MessageRole` The role of the participant. - `"assistant"` - `"user"` - `"tool"` - `"function"` - `"system"` - `"approval"` - `"summary"` - `agent_id: optional string` The unique identifier of the agent. - `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 or object { status, func_response, stderr, 2 more }` The list of approvals for this message. - `ApprovalReturn object { 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: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `LettaSchemasMessageToolReturnOutput object { status, func_response, stderr, 2 more }` - `status: "success" or "error"` The status of the tool call - `"success"` - `"error"` - `func_response: optional string or array of TextContent or ImageContent` The function response - either a string or list of content parts (text/image) - `string` - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `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. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `stderr: optional array of string` Captured stderr from the tool invocation - `stdout: optional array of string` Captured stdout (e.g. prints, logs) from the tool invocation - `tool_call_id: optional unknown` The ID for the tool call - `approve: optional boolean` Whether tool call is approved. - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `content: optional array of TextContent or ImageContent or ToolCallContent or 5 more` The content of the message. - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[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: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { 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: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { 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: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { 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: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `SummarizedReasoning object { 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 of object { index, text }` Summaries of the reasoning content. - `index: number` The index of the summary part. - `text: string` The text of the summary part. - `encrypted_content: optional string` The encrypted reasoning content. - `type: optional "summarized_reasoning"` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `conversation_id: optional string` The conversation this message belongs to - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `denial_reason: optional string` The reason the tool call request was denied. - `group_id: optional string` The multi-agent group that the message was sent in - `is_err: optional boolean` Whether this message is part of an error step. Used only for debugging purposes. - `last_updated_by_id: optional string` The id of the user that made this object. - `model: optional string` The model used to make the function call. - `name: optional string` For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called. - `otid: optional string` The offline threading id associated with this message - `run_id: optional string` The id of the run that this message was created in. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `step_id: optional string` The id of the step that this message was created in. - `tool_call_id: optional string` The ID of the tool call. Only applicable for role tool. - `tool_calls: optional array of object { id, function, type }` The list of tool calls requested. Only applicable for role assistant. - `id: string` - `function: object { arguments, name }` The function that the model called. - `arguments: string` - `name: string` - `type: "function"` - `"function"` - `tool_returns: optional array of object { status, func_response, stderr, 2 more }` Tool execution return information for prior tool calls - `status: "success" or "error"` The status of the tool call - `"success"` - `"error"` - `func_response: optional string or array of TextContent or ImageContent` The function response - either a string or list of content parts (text/image) - `string` - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `stderr: optional array of string` Captured stderr from the tool invocation - `stdout: optional array of string` Captured stdout (e.g. prints, logs) from the tool invocation - `tool_call_id: optional unknown` The ID for the tool call - `updated_at: optional string` The timestamp when the object was last updated. - `model: optional string` The name of the model used for this step. - `model_endpoint: optional string` The model endpoint url used for this step. - `model_handle: optional string` The model handle (e.g., 'openai/gpt-4o-mini') used for this step. - `origin: optional string` The surface that this agent step was initiated from. - `project_id: optional string` The project that the agent that executed this step belongs to (cloud only). - `prompt_tokens: optional number` The number of tokens in the prompt during this step. - `prompt_tokens_details: optional map[unknown]` Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens, cache_creation_tokens). - `provider_category: optional string` The category of the provider used for this step. - `provider_id: optional string` The unique identifier of the provider that was configured for this step - `provider_name: optional string` The name of the provider used for this step. - `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. - `status: optional "pending" or "success" or "failed" or "cancelled"` Status of a step execution - `"pending"` - `"success"` - `"failed"` - `"cancelled"` - `stop_reason: optional StopReasonType` The stop reason associated with the step. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `tags: optional array of string` Metadata tags. - `tid: optional string` The unique identifier of the transaction that processed this step. - `total_tokens: optional number` The total number of tokens processed by the agent during this step. - `trace_id: optional string` The trace id of the agent step. ### Example ```http curl https://api.letta.com/v1/runs/$RUN_ID/steps \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "id": "id", "agent_id": "agent_id", "cache_write_tokens": 0, "cached_input_tokens": 0, "completion_tokens": 0, "completion_tokens_details": { "foo": "bar" }, "context_window_limit": 0, "error_data": { "foo": "bar" }, "error_type": "error_type", "feedback": "positive", "messages": [ { "id": "message-123e4567-e89b-12d3-a456-426614174000", "role": "assistant", "agent_id": "agent_id", "approval_request_id": "approval_request_id", "approvals": [ { "approve": true, "tool_call_id": "tool_call_id", "reason": "reason", "type": "approval" } ], "approve": true, "batch_item_id": "batch_item_id", "content": [ { "text": "text", "signature": "signature", "type": "text" } ], "conversation_id": "conversation_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "denial_reason": "denial_reason", "group_id": "group_id", "is_err": true, "last_updated_by_id": "last_updated_by_id", "model": "model", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "step_id": "step_id", "tool_call_id": "tool_call_id", "tool_calls": [ { "id": "id", "function": { "arguments": "arguments", "name": "name" }, "type": "function" } ], "tool_returns": [ { "status": "success", "func_response": "string", "stderr": [ "string" ], "stdout": [ "string" ], "tool_call_id": {} } ], "updated_at": "2019-12-27T18:11:19.117Z" } ], "model": "model", "model_endpoint": "model_endpoint", "model_handle": "model_handle", "origin": "origin", "project_id": "project_id", "prompt_tokens": 0, "prompt_tokens_details": { "foo": "bar" }, "provider_category": "provider_category", "provider_id": "provider_id", "provider_name": "provider_name", "reasoning_tokens": 0, "request_id": "request_id", "run_id": "run_id", "status": "pending", "stop_reason": "end_turn", "tags": [ "string" ], "tid": "tid", "total_tokens": 0, "trace_id": "trace_id" } ] ``` # Trace ## Retrieve Trace For Run **get** `/v1/runs/{run_id}/trace` Retrieve OTEL trace spans for a run. Returns a filtered set of spans relevant for observability: - agent_step: Individual agent reasoning steps - tool executions: Tool call spans - Root span: The top-level request span - time_to_first_token: TTFT measurement span Requires ClickHouse to be configured for trace storage. ### Path Parameters - `run_id: string` ### Query Parameters - `limit: optional number` Maximum number of spans to return ### Example ```http curl https://api.letta.com/v1/runs/$RUN_ID/trace \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "foo": "bar" } ] ``` ## Domain Types ### Trace Retrieve Response - `TraceRetrieveResponse = array of map[unknown]`