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>'
import requests

url = "https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}")
  .header("x-api-key", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "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>"
    }
  ]
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<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 | null

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

​
activity
AgentActivityThread · object | null

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

​
usage
ConversationUsage · object | null

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.