> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Conversation Turn

> Send a message to the agent and wait for its reply.

Send one message and wait for the reply. The response is the conversation record: its `id` is the `conversation_id`, `result` holds the reply, and `status` is `completed` once the agent has answered (or `paused` when it is waiting on you, for example on a question or an approval).

To continue the conversation, send the next message with `id` set to that `conversation_id`. Omit `id` to start a new conversation. Sending a message to a conversation whose turn is still running cancels that turn and runs your new message instead; to add a message without cancelling, use [Send Conversation Message](/api-reference/v1/agents/conversations/send-message).

Set `output_schema` on the request to get the reply as JSON in that shape; without it the agent answers in its configured format, text by default.

The `sub_tasks` query parameter sets how sub-tasks the agent creates for other agents run inside this turn: `sync` inline, `async` in the background, `auto` per the agent's own choice. It does not change whether this call waits. The setting sticks to the conversation until you change it.

To see the reply as it is written, use the [streaming variant](/api-reference/v1/agents/conversations/run-turn-stream).

See the [Conversations overview](/api-reference/v1/agents/conversations/overview) for queueing, steering and reading the thread back.


## OpenAPI

````yaml POST /v1/agents/{agent_id}/conversations/invoke
openapi: 3.1.0
info:
  title: xpander.ai API Service
  description: |2-

        The xpander.ai API Service provides a unified REST API for managing AI agents,
        executing tasks, managing knowledge bases, and integrating with external systems.
        
        Features:
        - Agent Management: Create, update, deploy, and delete AI agents
        - Task Execution: Invoke agents with support for sync, async, and streaming modes
        - Knowledge Bases: Manage knowledge bases and documents for RAG workflows
        - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
        - MCP Integration: Model Context Protocol support for standardized AI interactions
        
        Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/agents/{agent_id}/conversations/invoke:
    post:
      tags:
        - API v1
        - Agents
        - Conversations
      summary: Run Conversation Turn (Sync)
      description: >-
        Send one message to the agent and wait for the reply. The response is
        the conversation record: `id` is the `conversation_id` (pass it as `id`
        to continue), `result` is the reply, `status` is the turn's status. Omit
        `id` to start a new conversation. Sending to a conversation whose turn
        is still running cancels that turn and runs the new message.
      operationId: Run_Conversation_Turn_Sync__v1_agents_agent_id_conversations_invoke_post
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
        - name: version
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Agent version to run.
            title: Version
          description: Agent version to run.
        - name: sub_tasks
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/SubTasksMode'
              - type: 'null'
            description: >-
              How the agent's own sub-tasks run inside this turn (not whether
              this API call blocks): 'sync' runs every sub-task inline, 'async'
              queues every sub-task, 'auto' restores the per-sub-task decision.
              The mode sticks to the conversation until changed.
            title: Sub Tasks
          description: >-
            How the agent's own sub-tasks run inside this turn (not whether this
            API call blocks): 'sync' runs every sub-task inline, 'async' queues
            every sub-task, 'auto' restores the per-sub-task decision. The mode
            sticks to the conversation until changed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentExecutionRequest'
            example:
              input:
                text: Summarize today's signups.
                user:
                  id: user-123
                  email: you@example.com
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentExecution'
              example:
                id: 7a7a7a7a-1111-2222-3333-555555555555
                agent_id: a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5
                organization_id: 0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e
                status: completed
                input:
                  text: Summarize today's signups.
                  user:
                    id: user-123
                    email: you@example.com
                result: 42 new signups today, up 12% week over week.
                created_at: '2026-07-28T20:59:02.915959Z'
                finished_at: '2026-07-28T20:59:51.661537Z'
                llm_model_provider: anthropic
                llm_model_name: claude-sonnet-5
                tokens:
                  input_tokens: 70216
                  output_tokens: 3496
                  total_tokens: 73712
                parent_execution: f0f0f0f0-1111-2222-3333-444444444444
                conversation_id: f0f0f0f0-1111-2222-3333-444444444444
                is_gateway: false
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SubTasksMode:
      type: string
      enum:
        - sync
        - async
        - auto
      title: SubTasksMode
    AgentExecutionRequest:
      properties:
        input:
          $ref: '#/components/schemas/AgentExecutionInput-Input'
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        payload_extension:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Payload Extension
        parent_execution_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Execution Id
        worker_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Worker Id
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        output_format:
          anyOf:
            - $ref: '#/components/schemas/OutputFormat'
            - type: 'null'
        output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Schema
        run_locally:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Run Locally
          default: false
        additional_context:
          anyOf:
            - type: string
            - type: 'null'
          title: Additional Context
        instructions_override:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions Override
        test_run_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Test Run Node Id
        expected_output:
          anyOf:
            - type: string
            - type: 'null'
          title: Expected Output
        events_streaming:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Events Streaming
          default: false
        mcp_servers:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Mcp Servers
          default: []
        triggering_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Triggering Agent Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        think_mode:
          anyOf:
            - $ref: '#/components/schemas/ThinkMode'
            - type: 'null'
          default: default
        disable_attachment_injection:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Disable Attachment Injection
          default: false
        user_tokens:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: User Tokens
        user_oidc_token:
          anyOf:
            - type: string
            - type: 'null'
          title: User Oidc Token
        return_metrics:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Return Metrics
          default: false
        llm_model_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm Model Provider
          description: >-
            Per-execution override for the LLM provider (e.g. 'openai',
            'anthropic'). Falls back to the agent's configured provider when
            unset.
        llm_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm Model Name
          description: >-
            Per-execution override for the LLM model name. Falls back to the
            agent's configured model when unset.
        llm_reasoning_effort:
          anyOf:
            - $ref: '#/components/schemas/LLMReasoningEffort'
            - type: 'null'
          description: >-
            Per-execution override for reasoning effort on reasoning-capable
            models.
        source_node_type:
          anyOf:
            - $ref: '#/components/schemas/SourceNodeType'
            - type: 'null'
          description: >-
            Surface that created this execution (mirrored to
            AgentExecutionHistory.source_node_type). Falls back to
            SourceNodeType.SDK at persist time when unset.
        is_app:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is App
          default: false
        is_steering:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Steering
          default: false
        sub_tasks_mode:
          anyOf:
            - $ref: '#/components/schemas/SubTasksMode'
            - type: 'null'
          description: >-
            Forces gateway sub-task dispatch: 'sync' runs all downstream
            sub-tasks inline, 'async' queues them all, 'auto' restores the
            computed per-sub-task decision.
      type: object
      required:
        - input
      title: AgentExecutionRequest
    AgentExecution:
      properties:
        id:
          type: string
          title: Id
        agent_id:
          type: string
          title: Agent Id
        organization_id:
          type: string
          title: Organization Id
        input:
          $ref: '#/components/schemas/AgentExecutionInput-Output'
        status:
          anyOf:
            - $ref: >-
                #/components/schemas/xpander_dev_utils__models__executions__AgentExecutionStatus
            - type: 'null'
          default: pending
        internal_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Internal Status
        last_executed_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Executed Node Id
        agent_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Version
        created_at:
          type: string
          format: date-time
          title: Created At
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        paused_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Paused At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
        parent_execution:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Execution
        sub_executions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Sub Executions
          default: []
        finished_sub_executions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Finished Sub Executions
          default: []
        should_update_parent:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Should Update Parent
          default: false
        is_manually_stopped:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Manually Stopped
          default: false
        is_background:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Background
          default: false
        payload_extension:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Payload Extension
        hitl_request:
          anyOf:
            - $ref: '#/components/schemas/HumanInTheLoopRequest'
            - type: 'null'
        pending_eca_request:
          anyOf:
            - $ref: '#/components/schemas/PendingECARequest'
            - type: 'null'
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        worker_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Worker Id
        additional_context:
          anyOf:
            - type: string
            - type: 'null'
          title: Additional Context
        instructions_override:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions Override
        expected_output:
          anyOf:
            - type: string
            - type: 'null'
          title: Expected Output
        test_run_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Test Run Node Id
        is_orchestration:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Orchestration
          default: false
        is_gateway:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Gateway
          default: false
        is_app:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is App
          default: false
        sub_tasks_mode:
          anyOf:
            - $ref: '#/components/schemas/SubTasksMode'
            - type: 'null'
        output_format:
          anyOf:
            - $ref: '#/components/schemas/OutputFormat'
            - type: 'null'
          default: text
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Id
        output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Schema
        events_streaming:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Events Streaming
          default: false
        used_mutating_tools:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Used Mutating Tools
          default: false
        is_continuous:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Continuous
          default: false
        mcp_servers:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Mcp Servers
          default: []
        triggering_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Triggering Agent Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        think_mode:
          anyOf:
            - $ref: '#/components/schemas/ThinkMode'
            - type: 'null'
          default: default
        disable_attachment_injection:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Disable Attachment Injection
          default: false
        deep_planning:
          anyOf:
            - $ref: '#/components/schemas/DeepPlanning'
            - type: 'null'
        must_deep_plan:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Must Deep Plan
          default: false
        execution_attempts:
          anyOf:
            - type: integer
            - type: 'null'
          title: Execution Attempts
          default: 1
        user_tokens:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: User Tokens
        user_oidc_token:
          anyOf:
            - type: string
            - type: 'null'
          title: User Oidc Token
        return_metrics:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Return Metrics
          default: false
        tokens:
          anyOf:
            - $ref: '#/components/schemas/LLMTokens'
            - type: 'null'
        llm_model_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm Model Provider
          description: >-
            Snapshot of the LLM provider used for this execution (request
            override or agent default at run time).
        llm_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm Model Name
          description: >-
            Snapshot of the LLM model name used for this execution (request
            override or agent default at run time).
        llm_reasoning_effort:
          anyOf:
            - $ref: '#/components/schemas/LLMReasoningEffort'
            - type: 'null'
          description: >-
            Snapshot of the reasoning effort applied during this execution, when
            supported by the model.
      type: object
      required:
        - id
        - agent_id
        - organization_id
        - input
        - created_at
      title: AgentExecution
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentExecutionInput-Input:
      properties:
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          default: ''
        files:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Files
          default: []
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Input'
            - type: 'null'
      type: object
      title: AgentExecutionInput
    OutputFormat:
      type: string
      enum:
        - text
        - markdown
        - json
        - voice
      title: OutputFormat
    ThinkMode:
      type: string
      enum:
        - default
        - harder
      title: ThinkMode
    LLMReasoningEffort:
      type: string
      enum:
        - low
        - medium
        - high
        - xhigh
      title: LLMReasoningEffort
    SourceNodeType:
      type: string
      enum:
        - workbench
        - sdk
        - task
        - assistant
        - webhook
        - mcp
        - a2a
        - telegram
        - slack
        - email
        - api
      title: SourceNodeType
    AgentExecutionInput-Output:
      properties:
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          default: ''
        files:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Files
          default: []
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Output'
            - type: 'null'
      type: object
      title: AgentExecutionInput
    xpander_dev_utils__models__executions__AgentExecutionStatus:
      type: string
      enum:
        - pending
        - executing
        - paused
        - error
        - failed
        - completed
        - stopped
      title: AgentExecutionStatus
    HumanInTheLoopRequest:
      properties:
        wait_node_id:
          type: string
          title: Wait Node Id
      type: object
      required:
        - wait_node_id
      title: HumanInTheLoopRequest
      description: |-
        Model representing human-in-the-loop approval records for tasks.

        Attributes:
            wait_node_id (str): The id of the node that triggered this HITL.
    PendingECARequest:
      properties:
        connector_name:
          type: string
          title: Connector Name
        auth_url:
          type: string
          title: Auth Url
      type: object
      required:
        - connector_name
        - auth_url
      title: PendingECARequest
    DeepPlanning:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
          default: false
        enforce:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enforce
          default: false
        started:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Started
          default: false
        question_raised:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Question Raised
          default: false
        tasks:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeepPlanningItem'
              type: array
            - type: 'null'
          title: Tasks
          default: []
      type: object
      title: DeepPlanning
    LLMTokens:
      properties:
        completion_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Completion Tokens
          default: 0
        prompt_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Prompt Tokens
          default: 0
        total_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Tokens
          default: 0
        cache_read_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Cache Read Tokens
          default: 0
        cache_write_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Cache Write Tokens
          default: 0
      type: object
      title: LLMTokens
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    User-Input:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
        email:
          type: string
          title: Email
        additional_attributes:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Additional Attributes
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          default: member
        is_super_admin:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Super Admin
          default: false
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
      type: object
      required:
        - email
      title: User
      description: |-
        Represents the details of a user.

        Attributes:
            id (Optional[str]): The unique identifier of the user. Defaults to None.
            first_name (Optional[str]): The first name of the user. Defaults to None.
            last_name (Optional[str]): The last name of the user. Defaults to None.
            email (str): The email address of the user. This field is required.
            additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service.
            role (Optional[str]): The user's role in the organization. Defaults to "member".
            is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False.
            timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None.
    User-Output:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
        email:
          type: string
          title: Email
        additional_attributes:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Additional Attributes
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          default: member
        is_super_admin:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Super Admin
          default: false
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
        display_name:
          type: string
          title: Display Name
          readOnly: true
      type: object
      required:
        - email
        - display_name
      title: User
      description: |-
        Represents the details of a user.

        Attributes:
            id (Optional[str]): The unique identifier of the user. Defaults to None.
            first_name (Optional[str]): The first name of the user. Defaults to None.
            last_name (Optional[str]): The last name of the user. Defaults to None.
            email (str): The email address of the user. This field is required.
            additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service.
            role (Optional[str]): The user's role in the organization. Defaults to "member".
            is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False.
            timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None.
    DeepPlanningItem:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        input:
          anyOf:
            - {}
            - type: 'null'
          title: Input
        output:
          anyOf:
            - {}
            - type: 'null'
          title: Output
        tool_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Name
        completed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Completed
          default: false
      type: object
      required:
        - id
        - title
      title: DeepPlanningItem
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````