> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions

> Every action an agent can run on a phone, with its parameters, results and platform support.

An agent works in a loop: **observe** the screen, **act**, then read the new screen that the action returns. This page lists every action. The same actions are available as [MCP tools](https://docs.appeeky.com/docs/phones/mcp.md) and through [`POST /v1/phones/invoke`](https://docs.appeeky.com/docs/phones/api#run-an-action). The parameter names on this page are the REST names. MCP names differ in a few places and are listed on the MCP page.

***

## Summary

| Action | `method` | Counts toward the rate limit | Can wait for approval |
| - | - | - | - |
| [List phones](#list-phones) | `devices` | No | No |
| [Observe](#observe) | `observe` | No | No |
| [Tap](#tap) | `tap` | Yes | Yes |
| [Long press](#long-press) | `long_press` | Yes | Yes |
| [Swipe](#swipe) | `swipe` | Yes | No |
| [Scroll](#scroll) | `scroll` | Yes | No |
| [Type](#type) | `type` | Yes | No |
| [Press a key](#press-a-key) | `key` | Yes | No |
| [Open an app](#open-an-app) | `open_app` | Yes | No |
| [List apps](#list-apps) | `list_apps` | No | No |
| [Push media](#push-media) | `push_media` | Yes | No |

Actions on one phone run one at a time, in the order they arrive.

***

## Common parameters

| Parameter | Type | Description |
| - | - | - |
| `device` | string | Device id from [List phones](#list-phones). Optional when exactly one phone is online. With several phones online and no `device`, the action fails and the message lists the ids |
| `observe` | boolean | For actions that change the screen. `true` (default) returns a fresh observation after the action. `false` returns only a confirmation, which is faster |

### Device ids

A device id is the Mac's name, a slash, and the phone's id on that Mac:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Studio-MacBook/adb:39111FDJH00ABC
Studio-MacBook/wda:127.0.0.1:8100
```

Always copy ids from [List phones](#list-phones).

### Targets

`tap`, `long_press` and `swipe` take a target. A target is one of:

| Target | Example | Use it when |
| - | - | - |
| Element number | `{ "element": 12 }` | The element is in the latest observation. Preferred |
| Point | `{ "x": 540, "y": 1200 }` | Nothing is numbered at that place. `x` and `y` are pixels of the screenshot, not of the phone's native screen |

Element numbers are valid only for the latest observation. After any action the numbers expire. Using an old number fails with `The screen changed since the last observation. Observe again before targeting elements by id.`

***

## List phones

`devices` returns the phones that are online across all your Macs.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "devices" }
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "kind": "devices",
  "devices": [
    {
      "id": "Studio-MacBook/adb:39111FDJH00ABC",
      "name": "Pixel_8",
      "platform": "android",
      "driver": "adb",
      "screen": { "width": 1080, "height": 2400 },
      "serial": "39111FDJH00ABC"
    }
  ],
  "problems": []
}
```

| Field | Description |
| - | - |
| `id` | Device id to pass as `device` |
| `name` | Phone name |
| `platform` | `android` or `ios` |
| `driver` | How the Mac controls the phone: `adb` for Android, `wda` for iPhone |
| `screen` | Screen size in native pixels |
| `serial` | The phone's serial number or UDID, when known |
| `problems` | Setup problems, filled only when no phone is online |

***

## Observe

`observe` takes a screenshot and finds the elements on screen.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "observe", "device": "Studio-MacBook/adb:39111FDJH00ABC" }
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "kind": "observation",
  "observation": {
    "device": { "id": "Studio-MacBook/adb:39111FDJH00ABC", "name": "Pixel_8", "platform": "android", "driver": "adb", "screen": { "width": 1080, "height": 2400 }, "serial": "39111FDJH00ABC" },
    "image": { "data": "<base64>", "mimeType": "image/jpeg", "width": 576, "height": 1280 },
    "elements": [
      { "id": 1, "label": "Search", "role": "button", "clickable": true, "x": 288, "y": 96 },
      { "id": 2, "label": "Message", "role": "text field", "clickable": true, "x": 250, "y": 1180 },
      { "id": 3, "label": "Send", "role": "button", "clickable": true, "x": 512, "y": 1180 }
    ],
    "description": "Pixel_8 (Studio-MacBook/adb:39111FDJH00ABC), screenshot 576x1280.\nTap by element id, or by x,y in screenshot pixels. Numbered boxes on the image match these ids:\n[1] \"Search\" (button, clickable) at 288,96\n[2] \"Message\" (text field, clickable) at 250,1180\n[3] \"Send\" (button, clickable) at 512,1180",
    "takenAt": "2026-11-19T10:15:00.000Z"
  }
}
```

| Field | Description |
| - | - |
| `image` | The screenshot as base64, with numbered boxes drawn over the elements. The longer edge is at most 1,280 pixels |
| `elements` | Up to 150 elements, numbered top to bottom, left to right. `x` and `y` are the element's center in screenshot pixels. `role` and `clickable` are present when known |
| `description` | The same list as text, ready to give to a model next to the image |
| `takenAt` | When the screenshot was taken |

When no elements are found on a screen, `elements` is empty and the agent taps by `x` and `y`.

***

## Tap

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "tap", "target": { "element": 3 } }
```

| Parameter | Type | Description |
| - | - | - |
| `target` | target | Required. Element number or point |
| `observe` | boolean | Default `true` |

A tap on an element whose label contains a word like Post, Send or Buy waits for your approval. The request stays open until you decide. See [Approvals and safety](https://docs.appeeky.com/docs/phones/approvals-and-safety.md).

Result with `observe: true` (default): an observation, same shape as [Observe](#observe), taken after the screen has settled.

Result with `observe: false`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "kind": "done", "action": "tap" }
```

All actions below that accept `observe` return results in the same two shapes.

***

## Long press

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "long_press", "target": { "element": 5 }, "durationMs": 1200 }
```

| Parameter | Type | Description |
| - | - | - |
| `target` | target | Required |
| `durationMs` | number | How long to hold, in milliseconds. Default `800` |
| `observe` | boolean | Default `true` |

A long press is checked for approval the same way as a tap.

***

## Swipe

Drags from one target to another. For plain scrolling, use [Scroll](#scroll).

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "swipe", "from": { "x": 500, "y": 1000 }, "to": { "x": 100, "y": 1000 }, "durationMs": 300 }
```

| Parameter | Type | Description |
| - | - | - |
| `from` | target | Required. Where the drag starts |
| `to` | target | Required. Where it ends |
| `durationMs` | number | Default `300` |
| `observe` | boolean | Default `true` |

***

## Scroll

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "scroll", "direction": "down", "amount": 0.5 }
```

| Parameter | Type | Description |
| - | - | - |
| `direction` | string | Required. `up`, `down`, `left` or `right`. `down` shows the content below, like reading further down a feed |
| `amount` | number | Fraction of the screen to scroll. Default `0.5` |
| `observe` | boolean | Default `true` |

***

## Type

Types into the text field that has focus. Tap the field first. A line break in the text presses Enter.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "type", "text": "Week 3 and still going" }
```

| Parameter | Type | Description |
| - | - | - |
| `text` | string | Required |
| `observe` | boolean | Default `true` |

On Android, text with accents, non-Latin letters or emoji needs a helper keyboard app on the phone. See [Connect phones](https://docs.appeeky.com/docs/phones/connect-phones.md#android).

***

## Press a key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "key", "key": "back" }
```

| Parameter | Type | Description |
| - | - | - |
| `key` | string | Required. See the table below |
| `observe` | boolean | Default `true` |

| Key | Android | iPhone |
| - | - | - |
| `home` | Yes | Yes |
| `back` | Yes | No |
| `enter` | Yes | Yes |
| `delete` | Yes | Yes |
| `app_switch` | Yes | No |
| `volume_up`, `volume_down` | Yes | Yes |
| `lock` | Yes | Yes |

A key the phone does not support fails with a message that lists the supported keys.

***

## Open an app

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "open_app", "appId": "com.zhiliaoapp.musically" }
```

| Parameter | Type | Description |
| - | - | - |
| `appId` | string | Required. The package name on Android, the bundle id on iPhone. Get it from [List apps](#list-apps) |
| `observe` | boolean | Default `true` |

On Android, an app that is not installed fails with `Could not open <appId>. Is it installed? Use list_apps to check.`

***

## List apps

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "list_apps" }
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "kind": "apps",
  "apps": [
    { "id": "com.instagram.android", "name": "com.instagram.android" },
    { "id": "com.zhiliaoapp.musically", "name": "com.zhiliaoapp.musically" }
  ]
}
```

On Android the list holds the apps you installed, not system apps, and `name` is the same as `id`. On iPhone `name` is the app's display name.

***

## Push media

Copies an image or video from a URL, or from a file on the Mac, into the phone's gallery. Apps can then pick it, for example when you create a post.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "method": "push_media", "url": "https://example.com/clip.mp4" }
```

| Parameter | Type | Description |
| - | - | - |
| `url` | string | A link to the file. Your Mac downloads it, then copies it to the phone |
| `path` | string | Or: an absolute path to a file on the Mac the phone is connected to |

Pass `url` or `path`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "kind": "media", "remotePath": "/sdcard/Pictures/agentthumbs/clip.mp4" }
```

* Works on **Android**. On iPhone it fails, because iPhones don't accept pushed media.
* A download larger than 512 MB is rejected.
* The file keeps its name. Use a link that ends in a real file name, such as `clip.mp4`.

> [!TIP]
>
> Links to generated media are often short-lived. Fetch a fresh link right before you push it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.