curl -X POST "https://app.runtm.com/api/v2/sessions/86e11104-.../refresh" \
-H "Authorization: Bearer runtm_xxx"
import requests, time
session_id = "86e11104-cdbb-42c9-bdc3-5212024ddb7b"
while True:
requests.post(
f"https://app.runtm.com/api/v2/sessions/{session_id}/refresh",
headers={"Authorization": "Bearer runtm_xxx"},
)
time.sleep(300) # every 5 min while the tab is open
setInterval(async () => {
await fetch(
"https://app.runtm.com/api/v2/sessions/86e11104-.../refresh",
{ method: "POST", headers: { "Authorization": "Bearer runtm_xxx" } }
);
}, 5 * 60 * 1000);
{
"ok": true
}
Refresh Sandbox TTL (v2)
Extend the sandbox TTL - the v2 keepalive that replaces /heartbeat
POST
/
api
/
v2
/
sessions
/
{session_id}
/
refresh
curl -X POST "https://app.runtm.com/api/v2/sessions/86e11104-.../refresh" \
-H "Authorization: Bearer runtm_xxx"
import requests, time
session_id = "86e11104-cdbb-42c9-bdc3-5212024ddb7b"
while True:
requests.post(
f"https://app.runtm.com/api/v2/sessions/{session_id}/refresh",
headers={"Authorization": "Bearer runtm_xxx"},
)
time.sleep(300) # every 5 min while the tab is open
setInterval(async () => {
await fetch(
"https://app.runtm.com/api/v2/sessions/86e11104-.../refresh",
{ method: "POST", headers: { "Authorization": "Bearer runtm_xxx" } }
);
}, 5 * 60 * 1000);
{
"ok": true
}
Extends the sandbox’s idle timeout so it stays alive while the user is interacting. Call this periodically (e.g. every 5 minutes) while a workspace tab is open.
This is the v2 replacement for the legacy
POST /api/sessions/{session_id}/heartbeat. Unlike heartbeat, /refresh does not rely on a side-effect-based keepalive. It explicitly extends the TTL via the sandbox provider’s REST API.
The session must be in running state.
Required scope: sessions:write
Path Parameters
string
required
The session ID.
Headers
string
required
Bearer token. Example:
Bearer runtm_xxxstring
Required when the session belongs to an organization.
Behavior
- Extends the sandbox TTL by
idle_timeout_minutes * 60seconds (default 30 minutes). - The sandbox provider caps duration at 3600s, so longer values are clamped.
- Reconciles with the sandbox provider before checking state. If the sandbox has been paused or expired between calls, returns an error so the caller can re-
startthe session.
Response
boolean
Always
true on success.Errors
| Status | Meaning |
|---|---|
400 | Session is not in running state, or has no sandbox |
404 | Session not found |
502 | Sandbox provider refresh call failed |
curl -X POST "https://app.runtm.com/api/v2/sessions/86e11104-.../refresh" \
-H "Authorization: Bearer runtm_xxx"
import requests, time
session_id = "86e11104-cdbb-42c9-bdc3-5212024ddb7b"
while True:
requests.post(
f"https://app.runtm.com/api/v2/sessions/{session_id}/refresh",
headers={"Authorization": "Bearer runtm_xxx"},
)
time.sleep(300) # every 5 min while the tab is open
setInterval(async () => {
await fetch(
"https://app.runtm.com/api/v2/sessions/86e11104-.../refresh",
{ method: "POST", headers: { "Authorization": "Bearer runtm_xxx" } }
);
}, 5 * 60 * 1000);
{
"ok": true
}