curl "https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b" \
-H "Authorization: Bearer runtm_xxx"
import requests
response = requests.get(
"https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b",
headers={"Authorization": "Bearer runtm_xxx"},
)
session = response.json()
print(f"State: {session['state']}")
print(f"Last prompt: {(session.get('last_prompt') or {}).get('status', 'idle')}")
const response = await fetch(
"https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b",
{ headers: { "Authorization": "Bearer runtm_xxx" } }
);
const session = await response.json();
console.log(`State: ${session.state}`);
console.log(`Last prompt: ${(session.last_prompt || {}).status || "idle"}`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "running",
"agent": "claude-code",
"template": "backend-service",
"created_at": "2026-05-09T21:00:00Z",
"expires_at": "2026-05-09T22:00:00Z",
"total_cost_usd": 0.23,
"prompt_count": 1,
"name": "Refactor billing service",
"github_repo": "acme/billing",
"last_prompt": {
"status": "completed",
"prompt_preview": "Build a REST API with FastAPI that manages TODO items",
"model": "sonnet",
"started_at": "2026-05-09T21:00:30Z",
"completed_at": "2026-05-09T21:04:12Z",
"cost_usd": 0.23,
"summary": "Created FastAPI app at /home/user/main.py with CRUD endpoints…",
"error": null,
"plan_mode": false
},
"prompt_history": [],
"lifecycle": {
"on_complete": "pause",
"ttl_minutes": 60,
"ttl_expires_at": "2026-05-09T22:00:00Z"
}
}
Get Session Status (v0)
Polling-friendly status endpoint for background agents
GET
/
api
/
v0
/
sessions
/
{session_id}
curl "https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b" \
-H "Authorization: Bearer runtm_xxx"
import requests
response = requests.get(
"https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b",
headers={"Authorization": "Bearer runtm_xxx"},
)
session = response.json()
print(f"State: {session['state']}")
print(f"Last prompt: {(session.get('last_prompt') or {}).get('status', 'idle')}")
const response = await fetch(
"https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b",
{ headers: { "Authorization": "Bearer runtm_xxx" } }
);
const session = await response.json();
console.log(`State: ${session.state}`);
console.log(`Last prompt: ${(session.last_prompt || {}).status || "idle"}`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "running",
"agent": "claude-code",
"template": "backend-service",
"created_at": "2026-05-09T21:00:00Z",
"expires_at": "2026-05-09T22:00:00Z",
"total_cost_usd": 0.23,
"prompt_count": 1,
"name": "Refactor billing service",
"github_repo": "acme/billing",
"last_prompt": {
"status": "completed",
"prompt_preview": "Build a REST API with FastAPI that manages TODO items",
"model": "sonnet",
"started_at": "2026-05-09T21:00:30Z",
"completed_at": "2026-05-09T21:04:12Z",
"cost_usd": 0.23,
"summary": "Created FastAPI app at /home/user/main.py with CRUD endpoints…",
"error": null,
"plan_mode": false
},
"prompt_history": [],
"lifecycle": {
"on_complete": "pause",
"ttl_minutes": 60,
"ttl_expires_at": "2026-05-09T22:00:00Z"
}
}
Returns the current state of a session along with
For high-volume agents, use webhooks instead of polling.
last_prompt (the polling status of the most recent prompt), prompt_history, and lifecycle policy. This is the endpoint to poll after POST /api/v0/sessions/launch or after sending a prompt via POST /api/v0/sessions/{id}/prompt.
The response shape is intentionally different from GET /api/sessions/{id} - v0 includes the polling fields needed for fire-and-forget agent workflows.
Required scope: sessions:read
Path Parameters
string
required
The session ID returned by
launch or create.Headers
string
required
Bearer token. Example:
Bearer runtm_xxxResponse
string
Session ID.
string
Sandbox state:
creating, running, paused, error.string
Coding agent (e.g.
claude-code).string | null
Template the session was scaffolded from.
string
ISO 8601 creation timestamp.
string | null
TTL expiry.
null for keep_alive sessions.number
Aggregate cost across all prompts.
integer
Number of prompts run in this session.
string | null
Display name.
string | null
GitHub
owner/repo link.object | null
Status of the most recent prompt - the primary polling field.
status-idle,running,completed,error,timed_outprompt_preview- first 200 chars of the promptmodel- model used (e.g.sonnet)started_at/completed_at- ISO 8601 timestampscost_usd- cost in USD for this promptsummary- first 500 chars of the agent’s final responseerror- error string ifstatusiserrorortimed_outplan_mode- whether plan mode was enabled
array
Ordered list of all prompts run in this session, each with the same shape as
last_prompt.object | null
Lifecycle policy applied at launch:
on_complete-pause,destroy, orkeep_alivettl_minutes- TTL in minutesttl_expires_at- ISO 8601 expiry timestamp
Polling pattern
import requests, time
session_id = "86e11104-..."
while True:
status = requests.get(
f"https://app.runtm.com/api/v0/sessions/{session_id}",
headers={"Authorization": "Bearer runtm_xxx"},
).json()
last = status.get("last_prompt") or {}
if last.get("status") in ("completed", "error", "timed_out"):
print(f"Done: {last['status']} (${last.get('cost_usd', 0):.4f})")
print(last.get("summary"))
break
time.sleep(5)
curl "https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b" \
-H "Authorization: Bearer runtm_xxx"
import requests
response = requests.get(
"https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b",
headers={"Authorization": "Bearer runtm_xxx"},
)
session = response.json()
print(f"State: {session['state']}")
print(f"Last prompt: {(session.get('last_prompt') or {}).get('status', 'idle')}")
const response = await fetch(
"https://app.runtm.com/api/v0/sessions/86e11104-cdbb-42c9-bdc3-5212024ddb7b",
{ headers: { "Authorization": "Bearer runtm_xxx" } }
);
const session = await response.json();
console.log(`State: ${session.state}`);
console.log(`Last prompt: ${(session.last_prompt || {}).status || "idle"}`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "running",
"agent": "claude-code",
"template": "backend-service",
"created_at": "2026-05-09T21:00:00Z",
"expires_at": "2026-05-09T22:00:00Z",
"total_cost_usd": 0.23,
"prompt_count": 1,
"name": "Refactor billing service",
"github_repo": "acme/billing",
"last_prompt": {
"status": "completed",
"prompt_preview": "Build a REST API with FastAPI that manages TODO items",
"model": "sonnet",
"started_at": "2026-05-09T21:00:30Z",
"completed_at": "2026-05-09T21:04:12Z",
"cost_usd": 0.23,
"summary": "Created FastAPI app at /home/user/main.py with CRUD endpoints…",
"error": null,
"plan_mode": false
},
"prompt_history": [],
"lifecycle": {
"on_complete": "pause",
"ttl_minutes": 60,
"ttl_expires_at": "2026-05-09T22:00:00Z"
}
}