Phones overview

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. See Connect your iPhone or Connect your Android phone.
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.

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

curl https://api.lusor.ai/v1/devices \
  -H "X-Api-Key: $LUSOR_API_KEY"

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"])

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.

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 and Follow a session.
Directly. Read the screen and send taps, swipes and text yourself. See Direct control.

Direct control

Read the screen and act on it one step at a time.

Chains and capture

Run several actions in one request and get the screen back.

Live view

Stream your own phone’s screen to your app.

Add and remove

Add and remove Lusor Phones with a price preview.

Location and timezone

Set the GPS location and timezone a Lusor Phone reports.

Language and identity

Change a Lusor Phone’s language, identity and advertising ID.

Internet and static IP

Read where a Lusor Phone’s traffic exits and its static IP.

Shell

Run a restricted shell command on a Lusor Phone.

Phone numbers and email

Read your workspace’s SMS and Agent Mail.

Get started

Agents & sessions

Phones

Billing and limits

Phones overview

List phones

See who is using a phone

Use a phone

Direct control

Chains and capture

Live view

Add and remove

Location and timezone

Language and identity

Internet and static IP

Shell

Phone numbers and email

​List phones

​See who is using a phone

​Use a phone

Direct control

Chains and capture

Live view

Add and remove

Location and timezone

Language and identity

Internet and static IP

Shell

Phone numbers and email

List phones

See who is using a phone

Use a phone