---
title: "Create an Android instance"
method: POST
path: "/v1/android_instances"
---

# Create an Android instance

`POST /v1/android_instances`

## Query parameters

- `wait` boolean
- `reuseIfExists` boolean

## Request body

- AndroidInstanceCreate
  - `metadata` object
    - `displayName` string
    - `labels` object
  - `spec` object
    - `clues` object[]
      - `kind` 'ClientIP' | 'OSVersion', required
      - `clientIp` string
      - `osVersion` string — The major version of Android, e.g. "13", "14" or "15".
    - `region` string — Where the instance will be created. If not given, the region is decided based on scheduling clues (client IP) and availability. A region is a preference, not a hard pin: the request always overflows to every other available region, ordered by proximity, when the preferred ones are full. Accepted values: * A specific region name (e.g. "us-west1"). It is tried first, then the remaining regions in order of proximity to it. Scheduling clues (client IP) are ignored when a region is given. * A region group name (e.g. "us", "eu"). Its member regions are tried first in their listed order, then the remaining regions by proximity to the first member. * A pipe-separated, ordered list of regions (e.g. "us-east1|us-west1"). Those are tried first in the given order, then the remaining regions by proximity to the first.
    - `inactivityTimeout` string, duration — After how many minutes of inactivity should the instance be terminated. The timer starts once the instance becomes ready. Example values 1m, 10m, 3h. Default is 3m. Providing "0" uses the organization's default inactivity timeout.
    - `hardTimeout` string, duration — After how many minutes should the instance be terminated. Example values 1m, 10m, 3h. Default is "0" which means no hard timeout.
    - `sandbox` SandboxSpec
      - `playwrightAndroid` object
        - `enabled` boolean
        - `version` '1.56.1-lim.1' | '1.60.0-lim.1'
    - `initialAssets` object[]
      - `kind` 'App' | 'Configuration', required
      - `configuration` object
        - `kind` 'ChromeFlag', required
        - `chromeFlag` 'enable-command-line-on-non-rooted-devices@1'
      - `source` 'URL' | 'URLs' | 'AssetName' | 'AssetNames' | 'AssetIDs'
      - `url` string
      - `assetName` string
      - `urls` string[]
      - `assetNames` string[]
      - `assetIds` string[]
    - `jurisdiction` 'us' | 'eu' | 'as' — Restricts scheduling to regions in the given jurisdiction. Unlike region, this is a hard constraint: the request never overflows to a region outside the jurisdiction and fails when no region in the jurisdiction has capacity. A region belongs to a jurisdiction when its name starts with the jurisdiction prefix, e.g. "eu-north1" is in "eu". A region preference pointing outside the jurisdiction is ignored.

## Response `200`

OK

- AndroidInstance
  - `metadata` object, required
    - `id` string, required
    - `displayName` string
    - `organizationId` string, required
    - `createdAt` string, date-time, required
    - `terminatedAt` string, date-time
    - `labels` object
  - `spec` object, required
    - `region` string, required — The region where the instance will be created. If not given, will be decided based on scheduling clues and availability.
    - `inactivityTimeout` string, duration, required — After how many minutes of inactivity should the instance be terminated. The timer starts once the instance becomes ready. Example values 1m, 10m, 3h. Default is 3m. Providing "0" uses the organization's default inactivity timeout.
    - `hardTimeout` string, duration — After how many minutes should the instance be terminated. Example values 1m, 10m, 3h. Default is "0" which means no hard timeout.
  - `status` object, required
    - `state` 'unknown' | 'creating' | 'assigned' | 'ready' | 'terminated', required
    - `apiUrl` string
    - `adbWebSocketUrl` string
    - `endpointWebSocketUrl` string
    - `signedStreamUrl` string
    - `mcpUrl` string
    - `targetHttpPortUrlPrefix` string
    - `token` string, required
    - `sandbox` AndroidSandboxStatus
      - `playwrightAndroid` object
        - `url` string
    - `errorMessage` string
    - `terminationReason` string — Machine-readable reason the instance was terminated. Always present once state is "terminated", never present before that. New values may be added over time, so treat any unrecognized value as "Unknown". Known values: - "UserRequested": terminated by a delete request to the API. - "InactivityTimeout": the timeout given in spec.inactivityTimeout elapsed. - "HardTimeout": the timeout given in spec.hardTimeout elapsed. - "Unknown": terminated for a cause the platform did not attribute, including instances that failed to get ready during creation. See errorMessage for details when available.

## Other responses

- `default` — Error

---

[API](https://skmtc.net/limrun-inc/apis/limrun-api.md) · [All operations](https://skmtc.net/limrun-inc/apis/limrun-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/limrun-inc/limrun-api/versions/0a3cd7959546/schema)