Handle long-running prompts

​

When to use this

• You need to cancel a prompt that is taking too long or going off track
• You want to undo file changes the agent made during a prompt
• You lost a WebSocket connection and need to recover the agent’s output
• You are choosing between REST polling and WebSocket streaming for your integration

​

Prerequisites

• An API key with sessions:prompt scope (and sessions:write for rewind)
• A running session with at least one prompt already submitted

​

Check prompt status

curl "https://app.runtm.com/api/sessions/${SESSION_ID}" \
  -H "Authorization: Bearer runtm_xxx"

{
  "last_prompt": {
    "status": "running",
    "prompt_preview": "Add user authentication...",
    "model": "sonnet",
    "started_at": "2026-05-09T15:18:31Z",
    "completed_at": null,
    "cost_usd": null
  }
}

​

Cancel a running prompt

import requests

headers = {"Authorization": "Bearer runtm_xxx"}
resp = requests.post(
    f"https://app.runtm.com/api/sessions/{SESSION_ID}/prompt/cancel",
    headers=headers,
)
print(resp.json())  # {"status": "cancelled", "session_id": "..."}

const resp = await fetch(
  `https://app.runtm.com/api/sessions/${SESSION_ID}/prompt/cancel`,
  { method: "POST", headers: { Authorization: "Bearer runtm_xxx" } },
);
console.log(await resp.json());

​

Rewind file changes

curl -X POST "https://app.runtm.com/api/sessions/${SESSION_ID}/prompt/rewind" \
  -H "Authorization: Bearer runtm_xxx" \
  -H "Content-Type: application/json" \
  -d '{"checkpoint_id": "ckpt_8f2b1c0d4a..."}'

• The agent made destructive changes you want to undo
• You want to try a different approach from the same starting point
• A prompt went off track and you want to restore the workspace

​

Replay prompt history

resp = requests.get(
    f"https://app.runtm.com/api/sessions/{SESSION_ID}/history",
    headers=headers,
    params={"agent_session_id": "ses_01J9..."},
)
data = resp.json()
print(f"{data['count']} events")
for event in data["events"]:
    if event["type"] == "user":
        print(f"User: {event['content'][:80]}")
    elif event["type"] == "completion":
        print(f"Done - cost: ${event.get('cost_usd', 0):.4f}")

const resp = await fetch(
  `https://app.runtm.com/api/sessions/${SESSION_ID}/history?agent_session_id=ses_01J9...`,
  { headers: { Authorization: "Bearer runtm_xxx" } },
);
const { events, count } = await resp.json();
console.log(`${count} events`);

​

REST vs WebSocket: choosing the right approach

• You want simplicity and do not need to display streaming events in a UI
• Your integration is a local script, coding agent, or CI pipeline
• You only need the final result

• You are building a UI that shows live agent output
• You want structured event types (tool calls, file edits, text deltas) as they happen
• You need the lowest-latency path from agent to client

​

Common patterns

​

Submit → wait → collect

import time

requests.post(
    f"https://app.runtm.com/api/sessions/{SESSION_ID}/prompt",
    headers=headers,
    json={"prompt": "Add a /health endpoint"},
)

while True:
    session = requests.get(
        f"https://app.runtm.com/api/sessions/{SESSION_ID}",
        headers=headers,
    ).json()
    status = session.get("last_prompt", {}).get("status")
    if status in ("completed", "error", "timed_out"):
        break
    time.sleep(3)

print(f"Prompt finished with status: {status}")

​

Guard against concurrent prompts

resp = requests.post(
    f"https://app.runtm.com/api/sessions/{SESSION_ID}/prompt",
    headers=headers,
    json={"prompt": "Fix the failing tests"},
)
data = resp.json()

if data.get("status") == "already_running":
    requests.post(
        f"https://app.runtm.com/api/sessions/{SESSION_ID}/prompt/cancel",
        headers=headers,
    )
    time.sleep(2)
    resp = requests.post(
        f"https://app.runtm.com/api/sessions/{SESSION_ID}/prompt",
        headers=headers,
        json={"prompt": "Fix the failing tests"},
    )

​

Next steps