---
canonical_url: "https://docs.composio.dev/toolkits/phone_harness"
markdown_url: "https://docs.composio.dev/toolkits/phone_harness.md"
product: "platform"
version: null
last_updated: null
---

# Phone Harness

Phone Harness provides cloud Android phone sessions for automated lifecycle management, observation, and ADB access.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 21
- **Triggers:** 0
- **Slug:** `PHONE_HARNESS`
- **Version:** 00000000_00

## Tools

### Create API Key

**Slug:** `PHONE_HARNESS_CREATE_API_KEY`

Create an account-wide API bearer key that can manage API keys. The raw key is shown only once; store it securely and never log it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `label` | string | No | Optional human-readable label for the new key. Omit for the provider default, or pass null to create an explicitly unlabeled key. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Session

**Slug:** `PHONE_HARNESS_CREATE_SESSION`

Start a temporary or saved Android emulator session and return its admitted session data plus the internally generated idempotency key. If the initial POST has an ambiguous transport failure, this action recovers or safely replays that same keyed request once. A provisioning result is not ready; poll PHONE_HARNESS_GET_SESSION until state is ready or terminal error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `profile_id` | string | No | Saved Android emulator profile ID from PHONE_HARNESS_GET_ACCOUNT. Omit to use a temporary Android emulator. |
| `timeout_seconds` | integer | No | Positive finite session duration in seconds, including provisioning. Defaults to 300; the provider rejects values too large to form a supported absolute timestamp. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Enable ADB

**Slug:** `PHONE_HARNESS_ENABLE_ADB`

Enable or re-enable ADB access for a ready Android session and return its current connection endpoint and sensitive unlock code. Repeated calls are idempotent.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Ready Android session ID for which to enable ADB. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### End Session

**Slug:** `PHONE_HARNESS_END_SESSION`

Request that a Phone Harness session end and billing closure be recorded. A cleanup_pending result is asynchronous and continues to consume capacity; use the durable create receipt to confirm cleanup_complete. Repeating cleanup after the session is gone can return session_not_found; that outcome does not prove release or cleanup, even on a repeated call.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Session ID to end. The ID is URL-encoded as one path segment. Obtain it from a Phone Harness session create or read action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account

**Slug:** `PHONE_HARNESS_GET_ACCOUNT`

Get the connected account's identity, balance, Android profile choices, active-session capacity, and whether a new session can be started.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get ADB

**Slug:** `PHONE_HARNESS_GET_ADB`

Get the current ADB state for an Android session. Returns exactly a disabled result or the enabled connection endpoint and sensitive unlock credential.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Android session ID whose ADB state should be read. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get API Health

**Slug:** `PHONE_HARNESS_GET_HEALTH`

Check public Phone Harness API-process liveness only. This does not certify phone availability, credits, capacity, video, or successful provisioning.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Owner Viewer

**Slug:** `PHONE_HARNESS_GET_OWNER_VIEWER`

Create a secret, short-lived capability for interactive owner control of a ready session. Embedding is restricted to the configured Phone Harness dashboard origin, not arbitrary third-party origins. Reconnecting does not extend the phone deadline. Return it only for secure handoff to the intended account owner; never log, persist, or publish it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Session ID for which to create an interactive owner viewer capability. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Recent History

**Slug:** `PHONE_HARNESS_GET_RECENT_HISTORY`

Return up to 100 finished sessions ordered by creation time descending. Use LIST_HISTORY instead when complete cursor-based traversal is needed.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Session

**Slug:** `PHONE_HARNESS_GET_SESSION`

Get one session's current lifecycle state, deadline, screen geometry, and ADB details. Use it to poll provisioning; state=error is a terminal startup failure, not success.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Session ID returned by PHONE_HARNESS_CREATE_SESSION or another session read. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Snapshot

**Slug:** `PHONE_HARNESS_GET_SNAPSHOT`

Download the latest still image from a ready Phone Harness session as a file. The image is PNG or JPEG. A no-frame-yet response is retryable after the session is ready and has rendered a frame.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Ready session ID whose current screen image should be downloaded. The ID is URL-encoded as one path segment. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create View-Only Link

**Slug:** `PHONE_HARNESS_GET_VIEWER`

Create a short-lived view-only link for an intended person to watch a live session. Return the link for secure handoff; it grants no interactive owner control and must not be logged or published.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Session ID for which to create a view-only link to give an intended viewer. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List API Keys

**Slug:** `PHONE_HARNESS_LIST_API_KEYS`

List metadata for the connected account's API keys, including hashes, labels, hints, creation times, and revocation times. This action never returns raw bearer keys.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List History

**Slug:** `PHONE_HARNESS_LIST_HISTORY`

Return one cursor-paginated page of finished-session history in newest-first order, with a next cursor for complete traversal.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum finished sessions to return in this page (1-100). |
| `cursor` | string | No | Opaque next_cursor from a previous response. Pass it unchanged; omit it for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Sessions

**Slug:** `PHONE_HARNESS_LIST_SESSIONS`

List all active account sessions, including provisioning, terminal-error, closing, and cleanup-pending entries.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Recover Create Request

**Slug:** `PHONE_HARNESS_RECOVER_CREATE_REQUEST`

Read the durable receipt for an idempotent session create to resolve an ambiguous create result or confirm asynchronous release cleanup.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_key` | string | Yes | Idempotency key returned by PHONE_HARNESS_CREATE_SESSION. Pass it unchanged to recover the durable create receipt. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Reset ADB Code

**Slug:** `PHONE_HARNESS_RESET_ADB_CODE`

Rotate the ADB unlock code for an Android session, invalidate the previous code, and close all existing ADB connections. Returns sensitive replacement connection details that must be used for subsequent connections.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Android session ID whose ADB unlock code should be rotated. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Reset Device

**Slug:** `PHONE_HARNESS_RESET_DEVICE`

Irreversibly erase and reprovision an assigned iPhone, deleting its apps, accounts, and data. The reset takes a few minutes; poll PHONE_HARNESS_GET_ACCOUNT until the device state is available before starting it again. Phone Harness refuses the reset while a session holds the device.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device_id` | string | Yes | iPhone device ID from PHONE_HARNESS_GET_ACCOUNT available profiles. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Reset Profile

**Slug:** `PHONE_HARNESS_RESET_PROFILE`

Irreversibly delete the saved Android profile's apps, logins, and data. The next session using its profile ID starts with a fresh phone. Phone Harness refuses the reset while a live session holds the profile phone.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Revoke ADB

**Slug:** `PHONE_HARNESS_REVOKE_ADB`

Revoke ADB access for an Android session. This changes only ADB access: the phone session remains active and session billing continues unaffected.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Android session ID whose ADB access should be revoked. Pass the opaque ID returned by Phone Harness unchanged. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Revoke API Key

**Slug:** `PHONE_HARNESS_REVOKE_API_KEY`

Idempotently revoke an API key by its hash. Identifier existence is not proven by a successful response, and active phone sessions are unaffected. Do not revoke the key used by the current connection if continued Phone Harness access is needed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key_hash` | string | Yes | Exact 64-character lowercase hexadecimal hash of the API key to revoke. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |