Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.litellm-agent-platform.ai/llms.txt

Use this file to discover all available pages before exploring further.

Returns the current state of a session. Use this endpoint to poll for the ready status after creating a session, and to read the agent’s latest response.

​
Request

GET /api/v1/managed_agents/sessions/{session_id}
Headers
HeaderValue
AuthorizationBearer <MASTER_KEY>

​
Path parameters

​
session_id
string
required
The unique ID of the session to retrieve.

​
Response

​
id
string
Unique session ID.
​
agent_id
string
ID of the agent this session belongs to.
​
status
string
Lifecycle state of the session. One of:
ValueDescription
creatingSandbox pod is starting. Poll until ready.
readySandbox is running and accepting messages.
failedBring-up failed. See failure_reason.
deadSession was stopped or cleaned up.
​
phase
string | null
Fine-grained bring-up phase. Useful for showing progress during creating. One of: creating_sandbox, pod_pending, pod_running, injecting_files, waiting_harness, harness_ready, cloning_repo, installing_deps, harness_listening, ready. null on legacy rows.
​
phase_detail
string | null
Optional human-readable detail for the current phase.
​
sandbox_url
string | null
Internal URL of the sandbox pod. Populated once the pod is running. null while creating.
​
tty_url
string | null
Browser-accessible WebSocket base URL for TUI harnesses (claude-code, codex). Connect with ?token=<tty_token> appended. null for API harnesses or while creating.
​
tty_token
string | null
Bearer token for the harness’s /tty WebSocket. Append as ?token=<value> when connecting. null if not configured.
​
response
object | null
The latest agent reply, stored after the most recent message completes. Shape: { parts: [{ type: "text", text: "..." }] }. null if no message has been sent yet.
​
created_at
string
ISO 8601 creation timestamp.
​
last_seen_at
string | null
ISO 8601 timestamp of the last message activity. null until the first message is sent. The idle timeout countdown starts from this value.
​
idle_timeout_ms
number
Milliseconds of inactivity after which the reconciler reaps a ready session. Currently 86400000 (24 hours).
​
failure_reason
string | null
Human-readable reason why the session entered failed or dead status. null on healthy sessions.

​
Example

curl "https://<your-platform-host>/api/v1/managed_agents/sessions/ses_01kabc" \
  -H "Authorization: Bearer $MASTER_KEY"

{
  "id": "ses_01kabc",
  "agent_id": "agt_01j9xyz",
  "status": "ready",
  "phase": "ready",
  "phase_detail": null,
  "sandbox_url": "http://10.0.1.42:4096",
  "tty_url": null,
  "tty_token": null,
  "response": null,
  "task_arn": "sandbox-ses_01kabc",
  "created_at": "2025-05-01T12:01:00.000Z",
  "last_seen_at": "2025-05-01T12:01:08.000Z",
  "idle_timeout_ms": 86400000,
  "failure_reason": null
}