Skip to main content
GET
/
v1
/
agents
/
{agent_id}
/
gateway
/
conversations
/
{conversation_id}
/
run-state
Conversation Run State
curl --request GET \
  --url https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}/run-state \
  --header 'x-api-key: <api-key>'
{
  "conversation_id": "<string>",
  "is_running": false,
  "is_steerable": false,
  "steer_target": "none",
  "active_child_id": "<string>",
  "queue_depth": 0,
  "queued_messages": [
    {
      "id": "<string>",
      "text": "",
      "files": [
        "<string>"
      ],
      "user": {},
      "enqueued_at": "<string>",
      "idempotency_key": "<string>"
    }
  ],
  "execution_status": "<string>",
  "conversation_state": "regular"
}
Poll this to see whether a turn is live and how many follow-ups are queued (with previews). It is Redis-backed and cheap, so it is safe to poll frequently. 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

Snapshot the UI uses to render run/queue/steer affordances.

​
conversation_id
string
required
​
is_running
boolean
default:false
​
is_steerable
boolean
default:false
​
steer_target
string
default:none
​
active_child_id
string | null
​
queue_depth
integer
default:0
​
queued_messages
GatewayQueuedMessage · object[]
​
execution_status
string | null
​
conversation_state
string
default:regular