> ## Documentation Index
> Fetch the complete documentation index at: https://phone-harness.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Session lifecycle

> Understand readiness, deadlines, billing time, and cleanup.

`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](/docs/guides/your-phone). Everything below applies to both.

| State          | What it means                                           | What to do                                                              |
| -------------- | ------------------------------------------------------- | ----------------------------------------------------------------------- |
| `provisioning` | The request was admitted; the phone is being prepared.  | Keep polling. Do not send phone operations yet.                         |
| `ready`        | The phone and API executor are available.               | Use the operations listed in `ops`.                                     |
| `error`        | Startup failed.                                         | Inspect the public error and create receipt; clean up if still present. |
| `closing`      | Closure was requested and cleanup may still be running. | Stop using the phone and wait for cleanup.                              |

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

| Clock                 | Starts                     | Ends                                        |
| --------------------- | -------------------------- | ------------------------------------------- |
| **Provisioning time** | Session creation/admission | API state becomes `ready`, or startup fails |
| **Session duration**  | Session creation/admission | `expires_at`, or an earlier End/closure     |
| **Billable use**      | The phone becomes `ready`  | Closure is recorded                         |

`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.

<Warning>
  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.
</Warning>

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.