GET /ui/observe
Capture structured elements in the foreground app.
This is a device HTTP route. Set DEVICE_URL to your reachable device URL; connection and examples explain how. Do not append this path to the public MCP URL.
Parameters
| Parameter | Type | Meaning |
|---|---|---|
bundleId | query string | Optional; must be foreground if provided; otherwise current foreground app. |
limit | query string | 1..1000; default 300. |
includeContainers | query string | Default false. GET flags accept 1 or true. |
includeHidden | query string | Default false. GET flags accept 1 or true. |
screenshot | query string | Default false; true includes screenshotURL for a cached PNG. GET flags accept 1 or true. |
Response
Observation JSON: schemaVersion,backend,observationId,bundleId,pid,processSessionId,timestamp,captureDurationMs,expiresInSeconds,screen,elements and traversal coverage. Each element includes ref, attributes, rect, actions and selector suggestions.
Example
curl --fail-with-body "$DEVICE_URL/ui/observe?limit=100&screenshot=1"Notes
Close the inspector before requesting a screenshot. Capture is not atomic: check timestamps. References belong to this observation and process, last at most 60 seconds, and may be evicted earlier. Refresh after navigation. screen uses nativePixels. See the HTTP workflow guide for all observation fields.
Check the HTTP status and any JSON error. HTTP workflows and error handling explain shared limits. All endpoints.