---
title: "Get a session"
method: GET
path: "/sessions/{sid}"
tags: ["Sessions"]
---

# Get a session

`GET /sessions/{sid}`

## Request

- Base URL: `https://api.phone-harness.com`
- URL: `https://api.phone-harness.com/sessions/{sid}`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `token`

Inspect state, deadline, geometry and advertised operations. A valid read-only watch grant may read only its own session. Ready does not mean a browser frame has been displayed.

## Path parameters

- `sid` string, required

## Response `200`

Session metadata.

- Session
  - `id` string, required: Opaque session ID.
  - `profile` string, nullable: The profile id this session holds, or null for a temporary phone.
  - `state` 'provisioning' | 'ready' | 'error' | 'closing', required
  - `progress` object: Only while `state` is `provisioning`: where the phone is. `queued` means every boot slot is busy and the phone starts as soon as one frees; `booting` means the phone is starting. `eta_seconds` is a typical remaining time for this start, not a promise; `still_starting` is true once that time is up and the phone is still starting.
    - `phase` 'queued' | 'booting', required
    - `queue_position` integer: Place in line, 1 = next. Present while `phase` is `queued`.
    - `eta_seconds` integer: Typical seconds left until the phone is ready.
    - `still_starting` boolean: True once the typical time is up and the phone is still starting; show that rather than a zero.
  - `platform` 'android' | 'ios': What the phone is: `android` or `ios`.
  - `kind` 'emulator' | 'device': How it runs: an `emulator`, or a real `device` (your own phone on a host).
  - `device` string, nullable, required: Display label in plain words ("Android emulator", "iPhone"); not a device connection address.
  - `close_requested` number, nullable, required: Time closure was requested. Unix time in seconds.
  - `cleanup_pending` boolean, required
  - `cleanup_status` 'complete' | 'allocation_uncertain' | 'pending' | 'null', nullable, required
  - `billing_mode` 'metered' | 'disabled', required
  - `phone` string, nullable, required: Legacy saved-phone ID. Null for a new disposable session.
  - `watch_url` string, uri, required: Sensitive read-only snapshot link. Not the interactive owner viewer.
  - `screen` ScreenSize, required
    - `w` integer, required: Width in device pixels.
    - `h` integer, required: Height in device pixels.
  - `age_s` integer, required: Rounded seconds since creation.
  - `ready_age_s` integer, required: Rounded seconds since readiness, stopped at closure; zero before readiness.
  - `idle_s` integer, required: Rounded seconds since the last activity recorded by the API. Does not extend or replace a selected session deadline.
  - `error` string: Public startup failure, if present.
  - `expires_at` number: Absolute session expiry, including provisioning. Unix time in seconds.
  - `timeout_seconds` integer: Selected finite duration from creation, in seconds.
  - `startup` StartupObservation: Optional startup provenance. Presence is not a latency measurement or a guarantee that prepared starts are available.
    - `mode` 'cold' | 'prepared', required
    - `pool` 'miss' | 'ineligible' | 'disabled' | 'hit', required
    - `preparation_ms` number: Optional preparation duration in milliseconds.
    - `inventory_age_ms` number: Optional inventory age in milliseconds.
  - `request_key` string: Returned in a creation response when an idempotency key was supplied.
  - `adb` SessionAdb: Present once the session is ready and ADB is enabled.
    - `host` string, required: DNS name of the ADB endpoint. Use the returned value.
    - `port` integer, required: TCP port dedicated to this phone while the session lives. Run adb connect host:port.
    - `code` string, required: The unlock code. After connecting, run adb shell unlock <code>. Anyone who has host, port and code can drive the phone until the session ends or the code is reset.
    - `expires_at` number, required: Unix timestamp in seconds when access expires. Never later than the session deadline; ADB access does not extend the session.

## Other responses

- `401`: Bad or missing bearer credential.
- `403`: Account access denied or rental access unavailable.
- `404`: No live session visible to the caller.
- `500`: Unexpected service error.

---

[API](https://skmtc.dev/phone-harness/apis/phone-harness-api.md) - [All operations](https://skmtc.dev/phone-harness/apis/phone-harness-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phone-harness/apis/phone-harness-api/revisions/5af8941102e5?raw)