Python example

This example uses Python’s standard library. It checks the operations advertised by the session, gives creation a stable idempotency key, and requests cleanup in finally. The client wait budget is independent of the phone’s selected duration. If that budget is exceeded, the example requests closure instead of leaving the phone running.

This is a real API example. Running it with a valid account key creates a metered session. The published example contains no credentials.

Copy the Python code below into phone_example.py, then run:

export PHONE_HARNESS_API_KEY="pck_REPLACE_WITH_YOUR_KEY"
python3 phone_example.py

import subprocess
import json
import os
import time
import urllib.error
import urllib.request
import uuid
from pathlib import Path

API = "https://api.phone-harness.com"
KEY = os.environ["PHONE_HARNESS_API_KEY"]


def request(method, path, body=None, request_key=None):
    headers = {"Authorization": f"Bearer {KEY}"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    if request_key is not None:
        headers["Idempotency-Key"] = request_key
    req = urllib.request.Request(
        API + path, data=data, headers=headers, method=method
    )
    with urllib.request.urlopen(req, timeout=40) as response:
        return json.load(response)


request_key = str(uuid.uuid4())
print("Create request key:", request_key)  # A receipt key, not a credential.
sid = None
try:
    # Reuse this key and this exact body if the creation result is ambiguous.
    created = request(
        "POST", "/sessions", {"timeout_seconds": 900}, request_key
    )
    sid = created["id"]
    deadline = time.monotonic() + 180  # Example client wait budget.
    while True:
        session = request("GET", f"/sessions/{sid}")
        if session["state"] == "ready":
            break
        if session["state"] in ("error", "closing"):
            raise RuntimeError(session.get("error", session["state"]))
        if time.monotonic() >= deadline:
            raise TimeoutError("Client stopped waiting for readiness")
        time.sleep(2)

    adb = session["adb"]
    serial = f"{adb['host']}:{adb['port']}"
    subprocess.run(["adb", "connect", serial], check=True)
    subprocess.run(["adb", "-s", serial, "shell", "unlock", adb["code"]], check=True)
    png = subprocess.run(["adb", "-s", serial, "exec-out", "screencap", "-p"],
                         check=True, capture_output=True).stdout
    Path("screenshot.png").write_bytes(png)
    print("Saved screenshot.png")
finally:
    if sid is None:
        # A lost POST response can still have admitted a session.
        try:
            receipt = request("GET", f"/sessions/requests/{request_key}")
            if not receipt["cleanup_complete"]:
                sid = receipt["id"]
        except Exception as recovery_error:
            print("Receipt recovery did not complete:", type(recovery_error).__name__)
            print("Keep the create request key and follow the retry guide.")
    if sid is not None:
        try:
            closed = request("DELETE", f"/sessions/{sid}")
            print("Cleanup response:", closed)
        except Exception as cleanup_error:
            print("Closure not confirmed:", type(cleanup_error).__name__)
            print("Recover the receipt with request key:", request_key)

If closure returns cleanup_pending: true, poll the create receipt to confirm cleanup_complete: true. A failed receipt lookup is not proof that no phone was created. Preserve the request key and use the retry and recovery flow. The finite session deadline still applies if your process exits or loses its connection. In a production integration, store request keys durably and recover unfinished requests when your process restarts.

Get started

Guides

Endpoints

Use cases