Conversation Run State
curl --request GET \
--url https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/run-state \
--header 'x-api-key: <api-key>'import requests
url = "https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/run-state"
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}/conversations/{conversation_id}/run-state', 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}/conversations/{conversation_id}/run-state",
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}/conversations/{conversation_id}/run-state"
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}/conversations/{conversation_id}/run-state")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/run-state")
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": "f0f0f0f0-1111-2222-3333-444444444444",
"is_running": false,
"is_steerable": false,
"steer_target": "none",
"active_child_id": null,
"queue_depth": 1,
"queued_messages": [
{
"id": "9d9d9d9d-8c8c-7b7b-6a6a-5f5f5f5f5f5f",
"text": "And who created it?",
"files": [],
"user": null,
"enqueued_at": "2026-07-28T21:11:24.343369+00:00",
"idempotency_key": null
}
],
"execution_status": "completed",
"conversation_state": "regular"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}REST API - Conversations
Conversation Run State
Cheap snapshot of a conversation’s run and queue state.
GET
/
v1
/
agents
/
{agent_id}
/
conversations
/
{conversation_id}
/
run-state
Conversation Run State
curl --request GET \
--url https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/run-state \
--header 'x-api-key: <api-key>'import requests
url = "https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/run-state"
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}/conversations/{conversation_id}/run-state', 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}/conversations/{conversation_id}/run-state",
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}/conversations/{conversation_id}/run-state"
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}/conversations/{conversation_id}/run-state")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/run-state")
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": "f0f0f0f0-1111-2222-3333-444444444444",
"is_running": false,
"is_steerable": false,
"steer_target": "none",
"active_child_id": null,
"queue_depth": 1,
"queued_messages": [
{
"id": "9d9d9d9d-8c8c-7b7b-6a6a-5f5f5f5f5f5f",
"text": "And who created it?",
"files": [],
"user": null,
"enqueued_at": "2026-07-28T21:11:24.343369+00:00",
"idempotency_key": null
}
],
"execution_status": "completed",
"conversation_state": "regular"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Poll this to see whether a turn is live, whether it can take a steer (
is_steerable, steer_target) and how many follow-ups are queued (with previews). It is cheap, so it is safe to poll frequently.
See the Conversations overview for the full conversation model.Authorizations
API Key for authentication
Response
Successful Response
Snapshot the UI uses to render run/queue/steer affordances.
Show child attributes
Show child attributes
Was this page helpful?

