Quickstart

This guide sends a task to an agent on one of your phones and reads back the result. You need: a Lusor workspace with at least one phone: a Lusor Phone, or your own iPhone (connect your iPhone) or Android phone (connect your Android phone). See Phones.

Create an API key

In the Lusor app, open Settings → API Keys and create a key. Copy it now: it is shown once.

export LUSOR_API_KEY="lusor_..."

See Authentication for how keys work.

Find your phone

List the phones in the key’s workspace:

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

Response

{
  "data": [
    {
      "id": "8e2c…",
      "name": "Pixel",
      "tier": "cloud_managed",
      "planId": "virtual",
      "connected": true,
      "pairedAt": "2026-10-01T12:00:00Z"
    }
  ]
}

Note the id of a phone with "connected": true.

Create an agent on that phone

curl https://api.lusor.ai/v1/agents \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quickstart agent",
    "devices": [{ "device_id": "<device id>" }]
  }'

The response is the agent. Keep data.id, the agent id. data.workspaceId is your workspace id, which you will need for direct phone control.

Your workspace may already have agents. GET /v1/agents lists them, so you can reuse one instead of creating one.

Send a task

curl https://api.lusor.ai/v1/agents/<agent id>/turns \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-1" \
  -d '{ "prompt": "Open Settings and tell me which software version this phone runs." }'

Response (202)

{
  "data": {
    "id": "4f1d…",
    "sessionId": "mobile_use_9c2e…",
    "status": "queued",
    "queued": false,
    "needsDevice": false,
    "deviceId": "8e2c…",
    "recording": true
  }
}

The agent starts working in the background. sessionId identifies the session that records its work. The Idempotency-Key header makes the request safe to retry: sending the same key again returns this turn instead of starting a second one.

Wait for it to finish

Poll the session’s status every few seconds:

curl https://api.lusor.ai/v1/sessions/<sessionId>/status \
  -H "X-Api-Key: $LUSOR_API_KEY"

The session is finished when status is completed (or complete), failed, or cancelled. If it is awaiting_human, the agent has asked you a question. Answer it with POST /v1/sessions/<sessionId>/hitl and it carries on. See Answer the agent.

Read the result

The agent’s reply is the turn’s summary. Read the agent to see its newest turns:

curl https://api.lusor.ai/v1/agents/<agent id> \
  -H "X-Api-Key: $LUSOR_API_KEY"

Each entry in data.turns has the turn’s sessionId, status and summary. For the session itself, read GET /v1/sessions/<sessionId>: error explains a failure, and output holds data the agent collected, if any. To see each step the agent took, read GET /v1/sessions/<sessionId>/events.

A complete script

The same flow in one script. It stops waiting if the agent asks you a question.

import os, time, uuid, requests

API = "https://api.lusor.ai/v1"
H = {"X-Api-Key": os.environ["LUSOR_API_KEY"]}
DONE = {"completed", "complete", "failed", "cancelled"}

agent_id = "<agent id>"
turn = requests.post(
    f"{API}/agents/{agent_id}/turns",
    headers={**H, "Idempotency-Key": str(uuid.uuid4())},
    json={"prompt": "Open Settings and tell me which software version this phone runs."},
).json()["data"]

session_id = turn["sessionId"]
while True:
    status = requests.get(f"{API}/sessions/{session_id}/status", headers=H).json()
    if status["status"] in DONE:
        break
    if status["status"] == "awaiting_human":
        print("The agent asked a question. See /agents/answer-the-agent.")
        break
    time.sleep(3)

agent = requests.get(f"{API}/agents/{agent_id}", headers=H).json()["data"]
reply = next((t for t in agent["turns"] if t["sessionId"] == session_id), {})
print(status["status"], reply.get("summary"), status.get("error"))

const API = "https://api.lusor.ai/v1";
const H = { "X-Api-Key": process.env.LUSOR_API_KEY };
const DONE = new Set(["completed", "complete", "failed", "cancelled"]);

const agentId = "<agent id>";
const res = await fetch(`${API}/agents/${agentId}/turns`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ prompt: "Open Settings and tell me which software version this phone runs." }),
});
const { data: turn } = await res.json();

let status;
do {
  await new Promise((r) => setTimeout(r, 3000));
  status = await (await fetch(`${API}/sessions/${turn.sessionId}/status`, { headers: H })).json();
} while (!DONE.has(status.status) && status.status !== "awaiting_human");

const { data: agent } = await (await fetch(`${API}/agents/${agentId}`, { headers: H })).json();
const reply = agent.turns.find((t) => t.sessionId === turn.sessionId);
console.log(status.status, reply?.summary, status.error);

Next steps

Send a turn

Queueing, safe retries, and sessions without an agent.

Follow a session

Statuses, events, artifacts and the session list.

Answer the agent

Reply when the agent asks you a question.

Direct phone control

Drive the phone yourself, action by action.

Get started

Agents & sessions

Phones

Billing and limits

A complete script

Next steps

Send a turn

Follow a session

Answer the agent

Direct phone control

​A complete script

​Next steps

Send a turn

Follow a session

Answer the agent

Direct phone control

A complete script

Next steps