Letta Runs API

openapi: 3.2.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:
    LettaUserMessageContentUnion:
      oneOf:
      - $ref: '#/components/schemas/TextContent'
      - $ref: '#/components/schemas/ImageContent'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextContent'
          image: '#/components/schemas/ImageContent'
    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.
    SummaryMessage:
      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: summary_message
          title: Message Type
          default: summary_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
        summary:
          type: string
          title: Summary
        compaction_stats:
          anyOf:
          - $ref: '#/components/schemas/CompactionStats'
          - type: 'null'
      type: object
      required:
      - id
      - date
      - summary
      title: SummaryMessage
      description: A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Message:
      properties:
        created_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Id
          description: The id of the user that made this object.
        last_updated_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated By Id
          description: The id of the user that made this object.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The timestamp when the object was created.
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: The timestamp when the object was last updated.
        id:
          type: string
          pattern: ^message-[a-fA-F0-9]{8}
          title: Id
          description: The human-friendly ID of the Message
          examples:
          - message-123e4567-e89b-12d3-a456-426614174000
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: The unique identifier of the agent.
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: The model used to make the function call.
        role:
          $ref: '#/components/schemas/MessageRole'
          description: The role of the participant.
        content:
          anyOf:
          - items:
              oneOf:
              - $ref: '#/components/schemas/TextContent'
              - $ref: '#/components/schemas/ImageContent'
              - $ref: '#/components/schemas/ToolCallContent'
              - $ref: '#/components/schemas/ToolReturnContent'
              - $ref: '#/components/schemas/ReasoningContent'
              - $ref: '#/components/schemas/RedactedReasoningContent'
              - $ref: '#/components/schemas/OmittedReasoningContent'
              - $ref: '#/components/schemas/SummarizedReasoningContent'
              discriminator:
                propertyName: type
                mapping:
                  image: '#/components/schemas/ImageContent'
                  omitted_reasoning: '#/components/schemas/OmittedReasoningContent'
                  reasoning: '#/components/schemas/ReasoningContent'
                  redacted_reasoning: '#/components/schemas/RedactedReasoningContent'
                  summarized_reasoning: '#/components/schemas/SummarizedReasoningContent'
                  text: '#/components/schemas/TextContent'
                  tool_call: '#/components/schemas/ToolCallContent'
                  tool_return: '#/components/schemas/ToolReturnContent'
            type: array
          - type: 'null'
          title: Content
          description: The content of the message.
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: 'For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.'
        tool_calls:
          anyOf:
          - items:
              $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall-Output'
            type: array
          - type: 'null'
          title: Tool Calls
          description: The list of tool calls requested. Only applicable for role assistant.
        tool_call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tool Call Id
          description: The ID of the tool call. Only applicable for role tool.
        step_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Step Id
          description: The id of the step that this message was created in.
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
          description: The id of the run that this message was created in.
        otid:
          anyOf:
          - type: string
          - type: 'null'
          title: Otid
          description: The offline threading id associated with this message
        tool_returns:
          anyOf:
          - items:
              $ref: '#/components/schemas/letta__schemas__message__ToolReturn-Output'
            type: array
          - type: 'null'
          title: Tool Returns
          description: Tool execution return information for prior tool calls
        group_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Id
          description: The multi-agent group that the message was sent in
        sender_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sender Id
          description: The id of the sender of the message, can be an identity id or agent id
        batch_item_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Batch Item Id
          description: The id of the LLMBatchItem that this message is associated with
        conversation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Conversation Id
          description: The conversation this message belongs to
        is_err:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Err
          description: Whether this message is part of an error step. Used only for debugging purposes.
        approval_request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Approval Request Id
          description: The id of the approval request if this message is associated with a tool call request.
        approve:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Approve
          description: Whether tool call is approved.
        denial_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Denial Reason
          description: The reason the tool call request was denied.
        approvals:
          anyOf:
          - items:
              anyOf:
              - $ref: '#/components/schemas/ApprovalReturn'
              - $ref: '#/components/schemas/letta__schemas__message__ToolReturn-Output'
            type: array
          - type: 'null'
          title: Approvals
          description: The list of approvals for this message.
      additionalProperties: false
      type: object
      required:
      - role
      title: Message
      description: "    Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats.\n\n    Attributes:\n        id (str): The unique identifier of the message.\n        role (MessageRole): The role of the participant.\n        text (str): The text of the message.\n        user_id (str): The unique identifier of the user.\n        agent_id (str): The unique identifier of the agent.\n        model (str): The model used to make the function call.\n        name (str): The name of the participant.\n        created_at (datetime): The time the message was created.\n        tool_calls (List[OpenAIToolCall,]): The list of tool calls requested.\n        tool_call_id (str): The id of the tool call.\n        step_id (str): The id of the step that this message was created in.\n        otid (str): The offline threading id associated with this message.\n        tool_returns (List[ToolReturn]): The list of tool returns requested.\n        group_id (str): The multi-agent group that the message was sent in.\n        sender_id (str): The id of the sender of the message, can be an identity id or agent id.\n        conversation_id (str): The conversation this message belongs to.\nt"
    UsageStatisticsCompletionTokenDetails:
      properties:
        reasoning_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reasoning Tokens
      type: object
      title: UsageStatisticsCompletionTokenDetails
    UrlImage:
      properties:
        type:
          type: string
          const: url
          title: Type
          description: The source type for the image.
          default: url
        url:
          type: string
          title: Url
          description: The URL of the image.
      type: object
      required:
      - url
      title: UrlImage
    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
    LettaToolReturnContentUnion:
      oneOf:
      - $ref: '#/components/schemas/TextContent'
      - $ref: '#/components/schemas/ImageContent'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextContent'
          image: '#/components/schemas/ImageContent'
    letta__schemas__letta_message__ToolReturn:
      properties:
        type:
          type: string
          const: tool
          title: Type
          description: The message type to be created.
          default: tool
        tool_return:
          anyOf:
          - items:
              $ref: '#/components/schemas/LettaToolReturnContentUnion'
            type: array
          - type: string
          title: Tool Return
          description: The tool return value - either a string or list of content parts (text/image)
        status:
          type: string
          enum:
       

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