Android Instances

The AndroidInstances resource provides methods to create, list, retrieve, and delete Android instances.

Methods

create()

Create a new Android instance.

create(
  params: AndroidInstanceCreateParams,
  options?: RequestOptions
): APIPromise<AndroidInstance>

Parameters

reuseIfExists

boolean

If there is another instance with given labels and region, return that one instead of creating a new instance.

wait

boolean

Return after the instance is ready to connect.

metadata

object

Metadata for the Android instance.

displayName

string

Human-readable display name for the instance.

labels

Record<string, string>

Key-value pairs for labeling the instance.

spec

object

Specification for the Android instance.

region

string

The region where the instance will be created. If not given, will be decided based on scheduling clues and availability.

inactivityTimeout

string

After how many minutes of inactivity should the instance be terminated. Example values: "1m", "10m", "3h". Default is "3m". Providing "0" disables inactivity checks altogether.

hardTimeout

string

After how many minutes should the instance be terminated. Example values: "1m", "10m", "3h". Default is "0" which means no hard timeout.

clues

Array<Clue>

Scheduling clues to help determine optimal instance placement.Each clue object has:

kind: "ClientIP" or "OSVersion"
clientIp: IP address (when kind is "ClientIP")
osVersion: Major Android version like "13", "14", or "15" (when kind is "OSVersion")

initialAssets

Array<InitialAsset>

Assets to load when the instance starts.Each asset object has:

kind: "App" or "Configuration"
source: "URL", "URLs", "AssetName", "AssetNames", or "AssetIDs"
url: Single URL (when source is "URL")
urls: Multiple URLs (when source is "URLs")
assetName: Asset name (when source is "AssetName")
assetNames: Multiple asset names (when source is "AssetNames")
assetIds: Asset IDs (when source is "AssetIDs")
configuration: Configuration object for kind "Configuration"

sandbox

object

Sandbox configuration.

playwrightAndroid

object

Playwright Android configuration.

enabled

boolean

Enable Playwright Android sandbox.

Returns

metadata

object

required

string

required

Unique identifier for the instance.

createdAt

string

required

ISO 8601 timestamp when the instance was created.

organizationId

string

required

Organization ID that owns this instance.

displayName

string

Human-readable display name.

labels

Record<string, string>

Key-value labels attached to the instance.

terminatedAt

string

ISO 8601 timestamp when the instance was terminated.

spec

object

required

inactivityTimeout

string

required

Configured inactivity timeout.

region

string

required

Region where the instance is running.

hardTimeout

string

Configured hard timeout.

status

object

required

token

string

required

Authentication token for connecting to the instance.

state

string

required

Current state: "unknown", "creating", "assigned", "ready", or "terminated".

adbWebSocketUrl

string

WebSocket URL for ADB connection.

endpointWebSocketUrl

string

WebSocket URL for endpoint connection.

targetHttpPortUrlPrefix

string

URL prefix for accessing HTTP ports on the instance.

errorMessage

string

Error message if the instance failed.

sandbox

object

playwrightAndroid

object

url

string

Playwright Android connection URL.

Example

const instance = await limrun.androidInstances.create({
  wait: true,
  metadata: {
    displayName: "Test Device",
    labels: {
      environment: "staging",
      team: "qa"
    }
  },
  spec: {
    region: "us-west",
    inactivityTimeout: "10m",
    hardTimeout: "1h",
    clues: [
      {
        kind: "OSVersion",
        osVersion: "14"
      }
    ],
    initialAssets: [
      {
        kind: "App",
        source: "URL",
        url: "https://example.com/app.apk"
      }
    ],
    sandbox: {
      playwrightAndroid: {
        enabled: true
      }
    }
  }
});

console.log(instance.metadata.id);
console.log(instance.status.state); // "ready"

list()

List Android instances with optional filters.

list(
  query?: AndroidInstanceListParams,
  options?: RequestOptions
): PagePromise<AndroidInstancesItems, AndroidInstance>

Parameters

labelSelector

string

Labels filter to apply to Android instances to return. Expects a comma-separated list of key=value pairs (e.g., "env=prod,region=us-west").

region

string

Region where the instance is scheduled on.

state

string

State filter to apply to Android instances to return. Each comma-separated state will be used as part of an OR clause, e.g. "assigned,ready" will return all instances that are either assigned or ready.Valid states: "creating", "assigned", "ready", "terminated", "unknown"

pageSize

number

Number of items per page.

pageToken

string

Token for pagination.

Returns

Returns a paginated list of AndroidInstance objects.

Example

// List all ready instances
const instances = await limrun.androidInstances.list({
  state: "ready"
});

for await (const instance of instances) {
  console.log(instance.metadata.id, instance.status.state);
}

// List instances with specific labels
const stagingInstances = await limrun.androidInstances.list({
  labelSelector: "environment=staging,team=qa"
});

get()

Get an Android instance by ID.

get(
  id: string,
  options?: RequestOptions
): APIPromise<AndroidInstance>

Parameters

string

required

The unique identifier of the Android instance.

Returns

Returns an AndroidInstance object with the same structure as described in the create() method.

Example

const instance = await limrun.androidInstances.get("instance_123");

console.log(instance.metadata.displayName);
console.log(instance.status.state);
console.log(instance.status.adbWebSocketUrl);

delete()

Delete an Android instance.

delete(
  id: string,
  options?: RequestOptions
): APIPromise<void>

Parameters

string

required

The unique identifier of the Android instance to delete.

Returns

Returns a promise that resolves when the instance is deleted.

Example

await limrun.androidInstances.delete("instance_123");
console.log("Instance deleted successfully");

Type Definitions