Skip to main content
POST /sessions accepts a request and returns 202. Use GET /sessions/{sid} to follow it. A session is either a temporary phone (the default) or your own phone: pass your account’s profile_id to get the phone you left last time. See Your phone. Everything below applies to both. After removal from the active runtime, GET /sessions/{sid} returns 404. Use the durable create receipt or history to inspect the completed request. A 404 alone is not a cleanup receipt.

​
Three different clocks

timeout_seconds defaults to 300 seconds. Pass a positive integer to select a different finite duration. Extremely large durations that cannot form a supported timestamp are rejected. There is no unlimited mode or session-extension endpoint.
Provisioning is included in the session duration. For example, if you select 900 seconds and provisioning takes 140 seconds, about 760 seconds remain after readiness. Choose enough time for startup, app installation, and your workflow.
Use the returned expires_at Unix timestamp, in seconds, as the session’s deadline. Reloading the dashboard, polling the API, sending input, or requesting another viewer does not extend it. Current sessions with a selected deadline do not use a separate inactivity cutoff.

​
Readiness is not the first video frame

ready means API operations can attach to the phone. Opening the browser viewer also requires obtaining a viewer URL, establishing the connection, and displaying video. Measure first visible frame separately if you are measuring the browser experience. age_s measures session age. ready_age_s is zero until ready, then measures elapsed ready time up to closure. Neither is a direct input-latency measurement.

​
End and cleanup

Call DELETE /sessions/{sid} when your workflow finishes, including when it fails. Closure stops new API operations and records the end of billable use. Cleanup can continue after the request returns.
  • 200, released: true: cleanup is confirmed.
  • 202, cleanup_pending: true: closure is accepted; cleanup is pending.
  • cleanup_status: allocation_uncertain: the service is still reconciling an uncertain allocation. Do not assume it is gone.
For sessions created with an idempotency key, poll GET /sessions/requests/{request_key} until cleanup_complete is true. Capacity can remain occupied while cleanup is pending. Your workflow should also tolerate early closure from exhausted credits, access revocation, service recovery, or startup failure. A selected duration is an upper bound, not a guarantee against interruptions.

​
Temporary data

App installations, logins, and files belong to that session’s temporary phone. They are not carried into a new session. Store screenshots or test outputs in your own system before ending the session. Saved-phone creation and resumption are not available.