> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List app installs
> Reports the backend's view of background app-install attempts on this device — status reflects the install ATTEMPT, not device ground truth; list-apps remains authoritative for what is actually installed. Records are in-memory and lost on service restart; terminal records are kept ~15 minutes. Not gated on device readiness, so it also answers while the device is offline or crashed.
Reports the backend's view of background app-install attempts on this device — one entry per `(platform, appId)` pair that has an `install-app` attempt in progress or recently finished.
`status` reflects the install **attempt**, not device ground truth. It is `running` from the moment `install-app` returns `202`, then flips to `succeeded` or `failed` once the background download + install finishes. `list-apps` remains authoritative for what is actually installed — a `succeeded` entry here is a strong signal, not a guarantee, and a device that goes offline mid-install can leave an entry `running` indefinitely until it is evicted. On iOS MDM devices specifically, `succeeded` only means the MDM `InstallApplication` command was accepted by the device's MDM channel — the device may still be downloading or installing, or may yet fail on-device — so `list-apps` remains the authoritative check there too.
Unlike most `Tools/Apps` endpoints, this one is **not gated on device readiness** — it answers from an in-memory job table, not from the device, so it also works while the device is offline, crashed, or otherwise unreachable. That's the situation this endpoint exists to surface: an install that fails because the device dropped mid-download has no other way to be observed by a caller.
On failure, `errorClass` narrows down what went wrong from a small closed set:
* `download_failed` — fetching the app asset failed
* `adb_install_failed` — the download succeeded but `adb install-multiple` failed
* `timeout` — the attempt exceeded its background time budget
* `panic` — the install goroutine panicked
* `failed` — anything else
Records are held in memory only and are lost on a service restart. Terminal (`succeeded`/`failed`) records are kept for roughly 15 minutes after their last update, then evicted; a `running` record is evicted after roughly 6 minutes without an update (longer than the install's own background time budget, so this only ever drops genuine leaks, not slow-but-live installs).
Records are scoped to the tenant that owned the device when the install attempt started: after an ownership transfer (e.g. reassignment or a BYOD re-pair), the new owner cannot see the previous tenant's install attempts, even while those records are still within their retention window above.
## OpenAPI
````yaml /api-reference/phones/tools.yaml get /devices/{deviceId}/apps/installs
openapi: 3.1.0
info:
title: Tools
version: v1
servers:
- url: https://api.mobilerun.ai
description: Droidrun Cloud API
security:
- bearerAuth: []
paths:
/devices/{deviceId}/apps/installs:
get:
tags:
- Apps
summary: List app installs
description: >-
Reports the backend's view of background app-install attempts on this
device — status reflects the install ATTEMPT, not device ground truth;
list-apps remains authoritative for what is actually installed. Records
are in-memory and lost on service restart; terminal records are kept ~15
minutes. Not gated on device readiness, so it also answers while the
device is offline or crashed.
operationId: list-app-installs
parameters:
- in: path
name: deviceId
required: true
schema:
type: string
- in: header
name: X-Device-Display-ID
schema:
default: 0
format: int64
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppInstallsOutputBody'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- bearerAuth: []
components:
schemas:
ListAppInstallsOutputBody:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://example.com/schemas/ListAppInstallsOutputBody.json
format: uri
readOnly: true
type: string
installs:
items:
$ref: '#/components/schemas/AppInstallStatus'
type:
- array
- 'null'
required:
- installs
type: object
ErrorModel:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://example.com/schemas/ErrorModel.json
format: uri
readOnly: true
type: string
detail:
description: >-
A human-readable explanation specific to this occurrence of the
problem.
examples:
- Property foo is required but is missing.
type: string
errors:
description: Optional list of individual error details
items:
$ref: '#/components/schemas/ErrorDetail'
type:
- array
- 'null'
instance:
description: >-
A URI reference that identifies the specific occurrence of the
problem.
examples:
- https://example.com/error-log/abc123
format: uri
type: string
status:
description: HTTP status code
examples:
- 400
format: int64
type: integer
title:
description: >-
A short, human-readable summary of the problem type. This value
should not change between occurrences of the error.
examples:
- Bad Request
type: string
type:
default: about:blank
description: A URI reference to human-readable documentation for the error.
examples:
- https://example.com/errors/example
format: uri
type: string
type: object
AppInstallStatus:
additionalProperties: false
properties:
appId:
description: Android package name or iOS bundle id
type: string
errorClass:
description: >-
Closed set: download_failed, adb_install_failed, panic, timeout,
failed. Only present when status is failed.
type: string
platform:
description: android or ios
type: string
startedAt:
format: date-time
type: string
status:
description: >-
On iOS MDM devices, succeeded means the install command was accepted
by the device's MDM channel, not that the install finished
on-device.
enum:
- running
- succeeded
- failed
type: string
updatedAt:
format: date-time
type: string
required:
- platform
- appId
- status
- startedAt
- updatedAt
type: object
ErrorDetail:
additionalProperties: false
properties:
location:
description: >-
Where the error occurred, e.g. 'body.items[3].tags' or
'path.thing-id'
type: string
message:
description: Error message text
type: string
value:
description: The value at the given location
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Opaque
description: Bearer token via Authorization header
````