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

# Phones overview

> The two kinds of phone in a workspace, how to list them, and how to see which agent is using one.

A **phone** is a device in your workspace that an agent, or your own code, can operate. There are two kinds.

| Kind | What it is | How it joins your workspace |
| - | - | - |
| **Your own phone** | An iPhone you own, connected through the Lusor Mac app, or an Android phone you own, connected through the Lusor Launcher app on the phone. It never uses Lusor Phone minutes. | Add it from the **Phones** page in the [Lusor app](https://app.lusor.ai). See [Connect your iPhone](https://docs.lusor.ai/help/connect-your-iphone.md) or [Connect your Android phone](https://docs.lusor.ai/help/connect-your-android.md). |
| **Lusor Phone** | A cloud phone that Lusor runs for you, with its own Internet connection. | Add it from the **Phones** page in the app, or with the API. See [Add and remove Lusor Phones](https://docs.lusor.ai/phones/add-and-remove.md). |

Every phone path in the API uses your workspace id and the phone's id:

```
https://api.lusor.ai/v1/workspaces/{workspaceId}/devices/{deviceId}/…
```

Your workspace id is the `workspaceId` field of any agent (`GET /v1/agents`). Phone ids come from the list below.

## List phones

```bash cURL theme={null}
curl https://api.lusor.ai/v1/devices \
  -H "X-Api-Key: $LUSOR_API_KEY"
```

```python Python theme={null}
import os, requests

r = requests.get(
    "https://api.lusor.ai/v1/devices",
    headers={"X-Api-Key": os.environ["LUSOR_API_KEY"]},
)
for phone in r.json()["data"]:
    print(phone["id"], phone["name"], phone["connected"])
```

```javascript Node.js theme={null}
const r = await fetch("https://api.lusor.ai/v1/devices", {
  headers: { "X-Api-Key": process.env.LUSOR_API_KEY },
});
const { data } = await r.json();
for (const phone of data) console.log(phone.id, phone.name, phone.connected);
```

`GET /v1/devices` lists every phone in the API key's workspace, including offline ones. `GET /v1/workspaces/{workspaceId}/devices` returns the same list for an explicit workspace.

| Field | Meaning |
| - | - |
| `id` | The phone's id, used in every phone path. |
| `name` | Display name. While the phone is offline, its last-known name or its id. |
| `connected` | Whether the phone is connected to Lusor right now. Actions on a disconnected phone fail. |
| `tier` | `cloud_managed` for a Lusor Phone, `byod` for your own phone. |
| `planId` | `personal` for your own phone. `virtual` or `glass` for a Lusor Phone. `unknown` for older phones without a recorded plan. |
| `platform` | The phone's operating system, when known. |
| `pairedAt` | When the phone joined the workspace. |
| `androidVersion`, `apiLevel`, `appVersion`, `connectedAt`, `lastSeen` | Live details, present only while the phone is connected. |
| `occupancy` | Which agents are using, waiting for, or attached to the phone. Same shape as the occupancy endpoint below. |

## See who is using a phone

A phone runs one session at a time. Further agent turns for it wait in a queue, oldest first.

```bash theme={null}
curl https://api.lusor.ai/v1/workspaces/$WS/devices/$DEVICE/occupancy \
  -H "X-Api-Key: $LUSOR_API_KEY"
```

| Field | Meaning |
| - | - |
| `active` | The run holding the phone now, with `sessionId`, `startedAt` and the agent's `agentId`, `agentName` and `agentColor`. `null` when the phone is idle. `agentId` is `null` for a run started without an agent. |
| `queue` | Agent turns waiting for the phone, oldest first, each with its `sessionId` and `queuedAt`. |
| `assigned` | The agents attached to the phone. |

## Use a phone

* **With an agent.** Attach the phone to an agent, then send it turns. See [Send a turn](https://docs.lusor.ai/agents/send-a-turn.md) and [Follow a session](https://docs.lusor.ai/agents/follow-a-session.md).
* **Directly.** Read the screen and send taps, swipes and text yourself. See [Direct control](https://docs.lusor.ai/phones/direct-control.md).

> [card] [Direct control](https://docs.lusor.ai/phones/direct-control.md)
>
> Read the screen and act on it one step at a time.

> [card] [Chains and capture](https://docs.lusor.ai/phones/chains-and-capture.md)
>
> Run several actions in one request and get the screen back.

> [card] [Live view](https://docs.lusor.ai/phones/live-view.md)
>
> Stream your own phone's screen to your app.

> [card] [Add and remove](https://docs.lusor.ai/phones/add-and-remove.md)
>
> Add and remove Lusor Phones with a price preview.

> [card] [Location and timezone](https://docs.lusor.ai/phones/location-and-timezone.md)
>
> Set the GPS location and timezone a Lusor Phone reports.

> [card] [Language and identity](https://docs.lusor.ai/phones/language-and-identity.md)
>
> Change a Lusor Phone's language, identity and advertising ID.

> [card] [Internet and static IP](https://docs.lusor.ai/phones/internet-and-static-ip.md)
>
> Read where a Lusor Phone's traffic exits and its static IP.

> [card] [Shell](https://docs.lusor.ai/phones/shell.md)
>
> Run a restricted shell command on a Lusor Phone.

> [card] [Phone numbers and email](https://docs.lusor.ai/phones/phone-numbers-and-email.md)
>
> Read your workspace's SMS and Agent Mail.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.