Letta Runs API

openapi: 3.1.0
info:
  title: Letta Admin Runs API
  version: 1.0.0
  description: REST API for Letta, the stateful agents platform. Manage agents, memory blocks, archival passages, sources, custom tools, MCP servers, multi-agent groups, runs, and streaming responses. Available as Letta Cloud (managed) at https://api.letta.com/v1 and as the self-hosted open-source server (Apache-2.0) typically run at http://localhost:8283.
  contact:
    name: Letta
    url: https://www.letta.com/
    email: support@letta.com
  license:
    name: Apache-2.0
    url: https://github.com/letta-ai/letta/blob/main/LICENSE
  x-logo:
    url: https://www.letta.com/favicon.ico
servers:
- url: https://api.letta.com
  description: Letta Cloud (managed)
- url: https://app.letta.com
  description: Letta Cloud (app)
- url: http://localhost:8283
  description: Self-hosted Letta server
security:
- bearerAuth: []
tags:
- name: Runs
  description: Inspect and manage agent runs (executions of an agent in response to a message).
paths:
  /v1/runs/:
    get:
      tags:
      - Runs
      summary: List Runs
      description: List all runs.
      operationId: list_runs
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The unique identifier of the agent associated with the run.
          title: Agent Id
        description: The unique identifier of the agent associated with the run.
      - name: agent_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.
          deprecated: true
          title: Agent Ids
        description: The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.
        deprecated: true
      - name: statuses
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter runs by status. Can specify multiple statuses.
          title: Statuses
        description: Filter runs by status. Can specify multiple statuses.
      - name: background
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: If True, filters for runs that were created in background mode.
          title: Background
        description: If True, filters for runs that were created in background mode.
      - name: stop_reason
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/StopReasonType'
          - type: 'null'
          description: Filter runs by stop reason.
          title: Stop Reason
        description: Filter runs by stop reason.
      - name: conversation_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter runs by conversation ID.
          title: Conversation Id
        description: Filter runs by conversation ID.
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order
          title: Before
        description: Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order
          title: After
        description: Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 1000
            minimum: 1
          - type: 'null'
          description: Maximum number of runs to return
          default: 100
          title: Limit
        description: Maximum number of runs to return
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first
          default: desc
          title: Order
        description: Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first
      - name: order_by
        in: query
        required: false
        schema:
          const: created_at
          type: string
          description: Field to sort by
          default: created_at
          title: Order By
        description: Field to sort by
      - name: active
        in: query
        required: false
        schema:
          type: boolean
          description: Filter for active runs.
          default: false
          title: Active
        description: Filter for active runs.
      - name: ascending
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field.
          deprecated: true
          default: false
          title: Ascending
        description: Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field.
        deprecated: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Run'
                title: Response List Runs
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/runs/active:
    get:
      tags:
      - Runs
      summary: List Active Runs
      description: List all active runs.
      operationId: list_active_runs
      deprecated: true
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The unique identifier of the agent associated with the run.
          title: Agent Id
        description: The unique identifier of the agent associated with the run.
      - name: background
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: If True, filters for runs that were created in background mode.
          title: Background
        description: If True, filters for runs that were created in background mode.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Run'
                title: Response List Active Runs
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/runs/{run_id}:
    get:
      tags:
      - Runs
      summary: Retrieve Run
      description: Get the status of a run.
      operationId: retrieve_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Runs
      summary: Delete Run
      description: Delete a run by its run_id.
      operationId: delete_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/runs/{run_id}/messages:
    get:
      tags:
      - Runs
      summary: List Messages for Run
      description: Get response messages associated with a run.
      operationId: list_messages_for_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order
          title: Before
        description: Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order
          title: After
        description: Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum number of messages to return
          default: 100
          title: Limit
        description: Maximum number of messages to return
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first
          default: asc
          title: Order
        description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first
      - name: order_by
        in: query
        required: false
        schema:
          const: created_at
          type: string
          description: Field to sort by
          default: created_at
          title: Order By
        description: Field to sort by
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LettaMessageUnion'
                title: Response List Messages For Run
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/runs/{run_id}/usage:
    get:
      tags:
      - Runs
      summary: Retrieve Usage for Run
      description: Get usage statistics for a run.
      operationId: retrieve_usage_for_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStatistics'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/runs/{run_id}/metrics:
    get:
      tags:
      - Runs
      summary: Retrieve Metrics for Run
      description: Get run metrics by run ID.
      operationId: retrieve_metrics_for_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunMetrics'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/runs/{run_id}/steps:
    get:
      tags:
      - Runs
      summary: List Steps for Run
      description: Get steps associated with a run with filtering options.
      operationId: list_steps_for_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Cursor for pagination
          title: Before
        description: Cursor for pagination
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Cursor for pagination
          title: After
        description: Cursor for pagination
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum number of messages to return
          default: 100
          title: Limit
        description: Maximum number of messages to return
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest first
          default: desc
          title: Order
        description: Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest first
      - name: order_by
        in: query
        required: false
        schema:
          const: created_at
          type: string
          description: Field to sort by
          default: created_at
          title: Order By
        description: Field to sort by
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Step'
                title: Response List Steps For Run
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/runs/{run_id}/trace:
    get:
      tags:
      - Runs
      summary: Retrieve Trace for Run
      description: '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.'
      operationId: retrieve_trace_for_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 5000
          minimum: 1
          description: Maximum number of spans to return
          default: 1000
          title: Limit
        description: Maximum number of spans to return
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                title: Response Retrieve Trace For Run
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/runs/{run_id}/stream:
    post:
      tags:
      - Runs
      summary: Retrieve Stream for Run
      operationId: retrieve_stream_for_run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveStreamRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: {}
            text/event-stream:
              description: Server-Sent Events stream
              schema:
                oneOf:
                - $ref: '#/components/schemas/SystemMessage'
                - $ref: '#/components/schemas/UserMessage'
                - $ref: '#/components/schemas/ReasoningMessage'
                - $ref: '#/components/schemas/HiddenReasoningMessage'
                - $ref: '#/components/schemas/ToolCallMessage'
                - $ref: '#/components/schemas/ToolReturnMessage'
                - $ref: '#/components/schemas/AssistantMessage'
                - $ref: '#/components/schemas/ApprovalRequestMessage'
                - $ref: '#/components/schemas/ApprovalResponseMessage'
                - $ref: '#/components/schemas/LettaPing'
                - $ref: '#/components/schemas/LettaErrorMessage'
                - $ref: '#/components/schemas/LettaStopReason'
                - $ref: '#/components/schemas/LettaUsageStatistics'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RunMetrics:
      properties:
        id:
          type: string
          title: Id
          description: The id of the run this metric belongs to (matches runs.id).
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: The unique identifier of the agent.
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: The project that the run belongs to (cloud only).
        run_start_ns:
          anyOf:
          - type: integer
          - type: 'null'
          title: Run Start Ns
          description: The timestamp of the start of the run in nanoseconds.
        run_ns:
          anyOf:
          - type: integer
          - type: 'null'
          title: Run Ns
          description: Total time for the run in nanoseconds.
        num_steps:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Steps
          description: The number of steps in the run.
        tools_used:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tools Used
          description: List of tool IDs that were used in this run.
        template_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Id
          description: The template ID that the run belongs to (cloud only).
        base_template_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Base Template Id
          description: The base template ID that the run belongs to (cloud only).
      additionalProperties: false
      type: object
      required:
      - id
      title: RunMetrics
    ApprovalReturn:
      properties:
        type:
          type: string
          const: approval
          title: Type
          description: The message type to be created.
          default: approval
        tool_call_id:
          type: string
          title: Tool Call Id
          description: The ID of the tool call that corresponds to this approval
        approve:
          type: boolean
          title: Approve
          description: Whether the tool has been approved
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: An optional explanation for the provided approval status
      type: object
      required:
      - tool_call_id
      - approve
      title: ApprovalReturn
    SystemMessage:
      properties:
        id:
          type: string
          title: Id
        date:
          type: string
          format: date-time
          title: Date
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        message_type:
          type: string
          const: system_message
          title: Message Type
          description: The type of the message.
          default: system_message
        otid:
          anyOf:
          - type: string
          - type: 'null'
          title: Otid
          description: 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.
        sender_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Id
        step_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Step Id
        is_err:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Err
        seq_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Seq Id
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        content:
          type: string
          title: Content
          description: The message content sent by the system
      type: object
      required:
      - id
      - date
      - content
      title: SystemMessage
      description: "A message generated by the system. Never streamed back on a response, only used for cursor pagination.\n\nArgs:\n    id (str): The ID of the message\n    date (datetime): The date the message was created in ISO format\n    name (Optional[str]): The name of the sender of the message\n    content (str): The message content sent by the system"
    StopReasonType:
      type: string
      enum:
      - 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
      title: StopReasonType
    CompactionStats:
      properties:
        trigger:
          type: string
          title: Trigger
          description: What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check')
        context_tokens_before:
          anyOf:
          - type: integer
          - type: 'null'
          title: Context Tokens Before
          description: Token count before compaction (from LLM usage stats, includes full context sent to LLM)
        context_tokens_after:
          anyOf:
          - type: integer
          - type: 'null'
          title: Context Tokens After
          description: Token count after compaction (message tokens only, does not include tool definitions)
        context_window:
          type: integer
          title: Context Window
          description: The model's context window size
        messages_count_before:
          type: integer
          title: Messages Count Before
          description: Number of messages before compaction
        messages_count_after:
          type: integer
          title: Messages Count After
          description: Number of messages after compaction
      type: object
      required:
      - trigger
      - context_window
      - messages_count_before
      - messages_count_after
      title: CompactionStats
      description: Statistics about a memory compaction operation.
    EventMessage:
      properties:
        id:
          type: string
          title: Id
        date:
          type: string
          format: date-time
          title: Date
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        message_type:
          type: string
          const: event_message
          title: Message Type
          default: event_message
        otid:
          anyOf:
          - type: string
          - type: 'null'
          title: Otid
          description: 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.
        sender_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Id
        step_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Step Id
        is_err:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Err
        seq_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Seq Id
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        event_type:
          type: string
          const: compaction
          title: Event Type
        event_data:
          additionalProperties: true
          type: object
          title: Event Data
      type: object
      required:
      - id
      - date
      - event_type
      - event_data
      title: EventMessage
      description: A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.
    ImageContent:
      properties:
        type:
          type: string
          const: image
          title: Type
          description: The type of the message.
          default: image
        source:
          oneOf:
          - $ref: '#/components/schemas/UrlImage'
          - $ref: '#/components/schemas/Base64Image'
          - $ref: '#/components/schemas/LettaImage'
          title: Source
          description: The source of the image.
          discriminator:
            propertyName: type
            mapping:
              base64: '#/components/schemas/Base64Image'
              letta: '#/components/schemas/LettaImage'
              url: '#/components/schemas/UrlImage'
      type: object
      required:
      - source
      title: ImageContent
    ToolReturnContent:
      properties:
        type:
          type: string
          const: tool_return
          title: Type
          description: Indicates this content represents a tool return event.
          default: tool_return
        tool_call_id:
          type: string
          title: Tool Call Id
          description: References the ID of the ToolCallContent that initiated this tool call.
        content:
          type: string
          title: Content
          description: The content returned by the tool execution.
        is_error:
          type: boolean
          title: Is Error
          description: Indicates whether the tool execution resulted in an error.
      type: object
      required:
      - tool_call_id
      - content
      - is_error
      title: ToolReturnContent
    MessageRole:
      type: string
      enum:
      - assistant
      - user
      - tool
      - function
      - system
      - approval
      - summary
      title: MessageRole
    AssistantMessage:
      properties:
        id:
          type: string
          title: Id
        date:
          type: string
          format: date-time
          title: Date
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        message_type:
          type: string
          const: assistant_message
          title: Message Type
          description: The type of the message.
          default: assistant_message
        otid:
          anyOf:
          - type: string
          - type: 'null'
          title: Otid
          description: 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.
        sender_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Id
        step_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Step Id
        is_err:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Err
        seq_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Seq Id
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        content:
          anyOf:
          - items:
              $ref: '#/components/schemas/LettaAssistantMessageContentUnion'
            type: array
          - type: string
          title: Content
          description: The message content sent by the agent (can be a string or an array of content parts)
      type: object
      required:
      - id
      - date
      - content
      title: AssistantMessage
      description: "A message sent by the LLM in response to user input. Used in the LLM context.\n\nArgs:\n    id (str): The ID of the message\n    date (datetime): The date the message was created in ISO format\n    name (Optional[str]): The name of the sender of the message\n    content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)"
    RunStatus:
      type: string
      enum:
      - created
      - running
      - completed
      - failed
      - cancelled
      title: RunStatus
      description: Status of the run.
    UsageStatisticsPromptTokenDetails:
      properties:
        cached_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cached Tokens
        cache_read_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cache Read Tokens
        cache_creation_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cache Creation Tokens
      type: object
      title: UsageStatisticsPromptTokenDetails
    ToolCallDelta:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        arguments:
          anyOf:
          - type: string
          - type: 'null'
          title: Arguments
        tool_call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tool Call Id
      type: object
      title: ToolCallDelta
    StepStatus:
      type: string
      enum:
      - pending
      - success
      - failed
      - cancelled
      title: StepStatus
      description: Status of a step execution
    HiddenReasoningMessage:
      properties:
        id:
          type: string
          title: Id
        date:
          type: string
          format: date-time
          title: Date
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        message_type:
          type: string
          const: hidden_reasoning_message
          title: Message Type
       

# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/openapi/letta-runs-api-openapi.yml