---
title: "Allocate a phone"
method: POST
path: "/phones/allocate"
tags: ["phones"]
---

# Allocate a phone

`POST /phones/allocate`

Allocates an Android phone and opens a session. Omit workflow_id for an interactive lease (drive the phone directly); set it to allocate for a workflow. Pass phone_id to pin a specific dedicated phone. If allocation setup fails the claim is rolled back, so you are never billed for a session that never starts.

## Request body

- PhoneAllocateRequest — Request body for allocating a phone.
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `capture` boolean — Capture media this session produces on the phone into the org's file library (default true). false disables capture for this session entirely.
  - `live_view` PhoneLiveViewOptions — Per-session options for the hosted live view.
    - `auth` 'token' | 'org' — Live-view auth mode: "token" (default) — capability URL, no sign-in; "org" — tokenless URL requiring sign-in + membership of the session's organization.
    - `disabled` boolean — Disable the live view for this session: no token is minted and live_view_url is omitted.
    - `view_only` boolean — Make the live view watch-only (server-enforced; input never reaches the phone).
  - `name` string — Optional session label (letters, numbers, dots, hyphens, underscores; max 64). Unique among the org's active sessions - allocating with a name already in use returns a conflict.
  - `phone_id` string — PhoneID pins allocation to a specific device (for dedicated devices).
  - `phone_type` 'android', required — Category of device to allocate.
  - `pool` 'shared' | 'dedicated' — Which pool to draw the phone from. Omit for shared. 'dedicated' claims any idle phone your organization rents; combine with phone_id to pin a specific one.
  - `recording` boolean — Record this session's screen (default true). false suppresses the video recording and rolling thumbnail entirely - no screen content is ever written.
  - `tags` object — Optional key->value labels for organizing sessions (max 50 tags; keys up to 40 chars, values up to 128).
  - `telemetry` boolean — Persist this session's telemetry spans (default true). false skips the durable trace store; the live telemetry stream still works while the session runs.
  - `ttl` PhoneSessionTTLOptions — Per-session idle-timeout override.
    - `idle_timeout_seconds` integer — Seconds with no user connection before the session is closed and its phone released (capped at 3600). Omit for no idle timeout: the session then runs until the 1-hour max-session cap.
  - `workflow_id` string — Workflow requesting allocation; nil for an interactive lease.

## Response `200`

OK

- PhoneAllocateResponse — Returned when a device has been successfully allocated.
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `control_url` string — WebSocket URL for driving the phone over the device control protocol.
  - `live_view_url` string — Hosted live-view page URL (live screen + interaction, iframe-embeddable). Contains a session-scoped capability token; treat as a secret. Dies with the session.
  - `phone_id` string, required — Allocated device's identifier.
  - `region` string — Physical region or location of the device.
  - `session_id` string, required — Device_allocations row id — the canonical session identifier (WS-ID2).
  - `telemetry_url` string — WebSocket URL for the session's live telemetry stream (trace spans + output logs, read-only). Dies with the session.
  - `workflow_started_at` string, date-time, required — Timestamp when the session started.

## Other responses

- `default` — Error

---

[API](https://skmtc.net/axilioai/apis/axilio-api.md) · [All operations](https://skmtc.net/axilioai/apis/axilio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/axilioai/axilio-api/revisions/108ab4b41051/schema)