longarm Batch Tasks

Batch tasks let longarm save reusable multi-step workflows and run them later from the app, REST API, or MCP.

Key behavior

one batch run can be active at a time
run requests return immediately with a runId
progress is checked through status and history
screenshots captured by screenshot steps are stored in batch history
default history retention is 30 runs

Task JSON shape

{
  "id": "bt_...",
  "name": "Open Settings and capture",
  "steps": [],
  "repeat": 1,
  "variables": {},
  "createdAt": "2026-07-13T00:00:00.000Z",
  "updatedAt": "2026-07-13T00:00:00.000Z"
}

For POST /api/batch and batch_save, provide name, steps, optional repeat, and optional variables. The server can assign IDs and timestamps.

Step JSON shape

{
  "id": "step_1",
  "type": "tap",
  "params": { "x": 540, "y": 1200, "duration": 80 },
  "repeat": 1,
  "delayAfterMs": 0,
  "continueOnError": false,
  "children": []
}

Supported step types

Free:

tap
long_press
screenshot
open_app
open_intent
overlay_show
overlay_hide
delay
set
ui_action
set_text
ui_scroll
wait_for_ui
loop

Plus:

swipe
pinch
two_finger_swipe
rotate

Common examples

Tap

{
  "type": "tap",
  "params": { "x": 540, "y": 1200, "duration": 80 }
}

Screenshot

{
  "type": "screenshot",
  "params": {
    "gridSize": 1,
    "gridUnit": "cm",
    "scale": true
  }
}

Open app

{
  "type": "open_app",
  "params": {
    "packageName": "com.android.settings"
  }
}

Delay

{
  "type": "delay",
  "params": { "ms": 1500 }
}

Variables

Use {{name}} substitution inside string params:

{
  "variables": {
    "packageName": "com.android.settings"
  },
  "steps": [
    {
      "type": "open_app",
      "params": { "packageName": "{{packageName}}" }
    }
  ]
}

Running and inspecting

Run saved tasks from the Batch tab, REST API, or MCP. Poll status or history with the returned runId, then inspect messages and screenshots in Batch History.

Longarm Batch Tasks