Skip to main content
GET
/
v1
/
agents
/
{agent_id}
/
gateway
/
conversations
/
{conversation_id}
Get Conversation
curl --request GET \
  --url https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id} \
  --header 'x-api-key: <api-key>'
{
  "conversation_id": "<string>",
  "execution": {
    "id": "<string>",
    "agent_id": "<string>",
    "organization_id": "<string>",
    "input": {
      "text": "",
      "files": [],
      "user": {
        "email": "<string>",
        "display_name": "<string>",
        "id": "<string>",
        "first_name": "<string>",
        "last_name": "<string>",
        "additional_attributes": {},
        "role": "member",
        "is_super_admin": false,
        "timezone": "<string>"
      }
    },
    "created_at": "2023-11-07T05:31:56Z",
    "status": "pending",
    "internal_status": "<string>",
    "last_executed_node_id": "<string>",
    "agent_version": "<string>",
    "started_at": "2023-11-07T05:31:56Z",
    "paused_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z",
    "result": "<string>",
    "parent_execution": "<string>",
    "sub_executions": [],
    "finished_sub_executions": [],
    "should_update_parent": false,
    "is_manually_stopped": false,
    "is_background": false,
    "payload_extension": {},
    "hitl_request": {
      "wait_node_id": "<string>"
    },
    "pending_eca_request": {
      "connector_name": "<string>",
      "auth_url": "<string>"
    },
    "source": "<string>",
    "worker_id": "<string>",
    "additional_context": "<string>",
    "instructions_override": "<string>",
    "expected_output": "<string>",
    "test_run_node_id": "<string>",
    "is_orchestration": false,
    "is_gateway": false,
    "output_format": "text",
    "voice_id": "<string>",
    "output_schema": {},
    "events_streaming": false,
    "used_mutating_tools": false,
    "is_continuous": false,
    "mcp_servers": [],
    "triggering_agent_id": "<string>",
    "title": "<string>",
    "think_mode": "default",
    "disable_attachment_injection": false,
    "deep_planning": {
      "enabled": false,
      "enforce": false,
      "started": false,
      "question_raised": false,
      "tasks": []
    },
    "execution_attempts": 1,
    "user_tokens": {},
    "user_oidc_token": "<string>",
    "return_metrics": false,
    "tokens": {
      "completion_tokens": 0,
      "prompt_tokens": 0,
      "total_tokens": 0
    },
    "llm_model_provider": "<string>",
    "llm_model_name": "<string>"
  },
  "activity": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "messages": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "content": {
          "text": "<string>",
          "files": []
        },
        "sub_execution_result": false,
        "is_steering": false,
        "user": {
          "email": "<string>",
          "display_name": "<string>",
          "id": "<string>",
          "first_name": "<string>",
          "last_name": "<string>",
          "additional_attributes": {},
          "role": "member",
          "is_super_admin": false,
          "timezone": "<string>"
        }
      }
    ],
    "user": {
      "email": "<string>",
      "display_name": "<string>",
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "additional_attributes": {},
      "role": "member",
      "is_super_admin": false,
      "timezone": "<string>"
    },
    "context_status": {
      "estimated_tokens": 123,
      "context_window": 123,
      "percent": 123,
      "auto_compact_threshold": 123,
      "emergency_threshold": 123,
      "compacting": false
    },
    "state": "regular"
  },
  "usage": {
    "cost": 0,
    "is_byok": false,
    "actions": 0,
    "ai_model": "<string>",
    "tokens": {
      "input": 0,
      "output": 0,
      "total": 0
    }
  },
  "sub_executions": [
    {
      "conversation_id": "<string>",
      "execution": {
        "id": "<string>",
        "agent_id": "<string>",
        "organization_id": "<string>",
        "input": {
          "text": "",
          "files": [],
          "user": {
            "email": "<string>",
            "display_name": "<string>",
            "id": "<string>",
            "first_name": "<string>",
            "last_name": "<string>",
            "additional_attributes": {},
            "role": "member",
            "is_super_admin": false,
            "timezone": "<string>"
          }
        },
        "created_at": "2023-11-07T05:31:56Z",
        "status": "pending",
        "internal_status": "<string>",
        "last_executed_node_id": "<string>",
        "agent_version": "<string>",
        "started_at": "2023-11-07T05:31:56Z",
        "paused_at": "2023-11-07T05:31:56Z",
        "finished_at": "2023-11-07T05:31:56Z",
        "result": "<string>",
        "parent_execution": "<string>",
        "sub_executions": [],
        "finished_sub_executions": [],
        "should_update_parent": false,
        "is_manually_stopped": false,
        "is_background": false,
        "payload_extension": {},
        "hitl_request": {
          "wait_node_id": "<string>"
        },
        "pending_eca_request": {
          "connector_name": "<string>",
          "auth_url": "<string>"
        },
        "source": "<string>",
        "worker_id": "<string>",
        "additional_context": "<string>",
        "instructions_override": "<string>",
        "expected_output": "<string>",
        "test_run_node_id": "<string>",
        "is_orchestration": false,
        "is_gateway": false,
        "output_format": "text",
        "voice_id": "<string>",
        "output_schema": {},
        "events_streaming": false,
        "used_mutating_tools": false,
        "is_continuous": false,
        "mcp_servers": [],
        "triggering_agent_id": "<string>",
        "title": "<string>",
        "think_mode": "default",
        "disable_attachment_injection": false,
        "deep_planning": {
          "enabled": false,
          "enforce": false,
          "started": false,
          "question_raised": false,
          "tasks": []
        },
        "execution_attempts": 1,
        "user_tokens": {},
        "user_oidc_token": "<string>",
        "return_metrics": false,
        "tokens": {
          "completion_tokens": 0,
          "prompt_tokens": 0,
          "total_tokens": 0
        },
        "llm_model_provider": "<string>",
        "llm_model_name": "<string>"
      },
      "activity": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "messages": [
          {
            "id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "content": {
              "text": "<string>",
              "files": []
            },
            "sub_execution_result": false,
            "is_steering": false,
            "user": {
              "email": "<string>",
              "display_name": "<string>",
              "id": "<string>",
              "first_name": "<string>",
              "last_name": "<string>",
              "additional_attributes": {},
              "role": "member",
              "is_super_admin": false,
              "timezone": "<string>"
            }
          }
        ],
        "user": {
          "email": "<string>",
          "display_name": "<string>",
          "id": "<string>",
          "first_name": "<string>",
          "last_name": "<string>",
          "additional_attributes": {},
          "role": "member",
          "is_super_admin": false,
          "timezone": "<string>"
        },
        "context_status": {
          "estimated_tokens": 123,
          "context_window": 123,
          "percent": 123,
          "auto_compact_threshold": 123,
          "emergency_threshold": 123,
          "compacting": false
        },
        "state": "regular"
      },
      "usage": {
        "cost": 0,
        "is_byok": false,
        "actions": 0,
        "ai_model": "<string>",
        "tokens": {
          "input": 0,
          "output": 0,
          "total": 0
        }
      },
      "feedbacks": [
        {
          "message_id": "<string>",
          "is_positive": true,
          "id": "<string>",
          "agent_id": "<string>",
          "conversation_id": "<string>",
          "user_id": "<string>",
          "comment": "<string>",
          "created_at": "<string>",
          "updated_at": "<string>"
        }
      ]
    }
  ],
  "feedbacks": [
    {
      "message_id": "<string>",
      "is_positive": true,
      "id": "<string>",
      "agent_id": "<string>",
      "conversation_id": "<string>",
      "user_id": "<string>",
      "comment": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ]
}
Returns the parent execution row, the full activity thread, aggregate cost / token usage, and every sub-execution’s (execution, activity, usage) triple. See the Agent Gateway overview for the full conversation model.

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required
​
conversation_id
string
required

Response

Successful Response

Combined view of one chat conversation.

conversation_id is the parent gateway execution id, which is also the activity-thread id. execution, activity, and usage can each be independently None when the upstream is unavailable — the route returns 404 only when BOTH execution AND activity are missing.

usage at this root level is aggregated across the parent execution AND every entry in sub_executions (single upstream call to the llm_usage:aggregate endpoint). Per-sub usage is mirrored on each SubExecutionResponse.usage so clients don't have to fan-out.

​
conversation_id
string
required
​
execution
AgentExecution · object

Parent gateway execution row (status, result, sub_executions, deep_planning, …).

​
activity
AgentActivityThread · object

Ordered message list (user, agent, tool calls, reasoning, …).

​
usage
ConversationUsage · object

Aggregate cost + token usage over parent + every sub-execution. Best-effort.

​
sub_executions
SubExecutionResponse · object[]

Triple-shape entry for every sub-execution spawned by this conversation.

​
feedbacks
MessageFeedbackItem · object[]

Per-message feedback rows recorded against the parent execution.