---
title: "Execute a batch of computer actions sequentially"
method: POST
path: "/computer/batch"
---

# Execute a batch of computer actions sequentially

`POST /computer/batch`

Execute an ordered list of computer actions in a single API call. Actions are performed
sequentially while holding an exclusive lock, so no other input operations can interleave.
Execution stops on the first error and the response indicates which action failed.
This is useful for chaining deterministic sequences of mouse and keyboard actions
without paying network round-trip latency for each individual action.

## Request body

- BatchComputerActionRequest — A batch of computer actions to execute sequentially.
  - `actions` ComputerAction[], required — Ordered list of actions to execute. Execution stops on the first error.
    - `type` 'click_mouse' | 'move_mouse' | 'type_text' | 'press_key' | 'scroll' | 'drag_mouse' | 'set_cursor' | 'sleep', required — The type of action to perform.
    - `click_mouse` ClickMouseRequest
      - `button` 'left' | 'right' | 'middle' | 'back' | 'forward' — Mouse button to interact with
      - `click_type` 'down' | 'up' | 'click' — Type of click action
      - `x` integer, required — X coordinate of the click position
      - `y` integer, required — Y coordinate of the click position
      - `hold_keys` string[] — Modifier keys to hold during the click
      - `num_clicks` integer — Number of times to repeat the click
    - `move_mouse` MoveMouseRequest
      - `x` integer, required — X coordinate to move the cursor to
      - `y` integer, required — Y coordinate to move the cursor to
      - `hold_keys` string[] — Modifier keys to hold during the move
      - `smooth` boolean — Use human-like Bezier curve path instead of instant mouse movement.
      - `duration_ms` integer — Target total duration in milliseconds for the mouse movement when smooth=true. Omit for automatic timing based on distance.
    - `type_text` TypeTextRequest
      - `text` string, required — Text to type on the host computer
      - `delay` integer — Delay in milliseconds between keystrokes. Ignored when smooth is true.
      - `smooth` boolean — Use human-like variable keystroke timing instead of a fixed delay. Defaults to true (same as moveMouse/dragMouse). Set to false for xdotool typing with an optional fixed delay between keys (delay=0 is instant). When true, text is typed in word-sized chunks with variable intra-word delays and natural inter-word pauses. The delay field is ignored when smooth is true.
      - `typo_chance` number — Per-character typo injection rate; mistakes are corrected with backspace. Default 0. Only applies when smooth is true (silently ignored when smooth is false).
    - `press_key` PressKeyRequest
      - `keys` string[], required — List of key symbols to press. Each item should be a key symbol supported by xdotool (see X11 keysym definitions). Examples include "Return", "Shift", "Ctrl", "Alt", "F5". Items in this list could also be combinations, e.g. "Ctrl+t" or "Ctrl+Shift+Tab".
      - `duration` integer — Duration to hold the keys down in milliseconds. If omitted or 0, keys are tapped.
      - `hold_keys` string[] — Optional modifier keys to hold during the key press sequence.
    - `scroll` ScrollRequest
      - `x` integer, required — X coordinate at which to perform the scroll
      - `y` integer, required — Y coordinate at which to perform the scroll
      - `delta_x` integer — Horizontal scroll amount. Positive scrolls right, negative scrolls left.
      - `delta_y` integer — Vertical scroll amount. Positive scrolls down, negative scrolls up.
      - `hold_keys` string[] — Modifier keys to hold during the scroll
    - `drag_mouse` DragMouseRequest
      - `path` array[], required — Ordered list of [x, y] coordinate pairs to move through while dragging. Must contain at least 2 points.
        - integer[]
      - `button` 'left' | 'middle' | 'right' — Mouse button to drag with
      - `delay` integer — Delay in milliseconds between button down and starting to move along the path.
      - `steps_per_segment` integer — Number of relative move steps per segment in the path. Ignored when smooth=true. Minimum 1.
      - `step_delay_ms` integer — Delay in milliseconds between relative steps while dragging. Ignored when smooth=true.
      - `smooth` boolean — Use human-like Bezier curves between path waypoints instead of linear interpolation. When true, steps_per_segment and step_delay_ms are ignored.
      - `duration_ms` integer — Target total duration in milliseconds for the entire drag movement when smooth=true. Omit for automatic timing based on total path length.
      - `hold_keys` string[] — Modifier keys to hold during the drag
    - `set_cursor` SetCursorRequest
      - `hidden` boolean, required — Whether the cursor should be hidden
    - `sleep` SleepAction — Pause execution for a specified duration.
      - `duration_ms` integer, required — Duration to sleep in milliseconds.

## Response `200`

Batch executed successfully

## Other responses

- `400` — Bad Request
- `500` — Internal Server Error

## Changes

> 52 revisions in range; 8 could not be searched.

- **2026-04-08** `56d552d7d8a6` — 2 info
  - added the new optional request property `actions/items/type_text/smooth`
  - added the new optional request property `actions/items/type_text/typo_chance`
- **2026-03-09** `d3dfd79e3308` — 2 info
  - added the new optional request property `actions/items/drag_mouse/duration_ms`
  - added the new optional request property `actions/items/drag_mouse/smooth`
- **2026-02-23** `a881622dd82b` — 2 info
  - added the new optional request property `actions/items/move_mouse/duration_ms`
  - added the new optional request property `actions/items/move_mouse/smooth`
- **2026-02-05** `5683ed70e314` — 1 info
  - endpoint added
- **2025-06-27** `f980a92ab23f` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/kernel/apis/kernel-images-api/changes/computer/batch/post.md)

---

[API](https://skmtc.dev/kernel/apis/kernel-images-api.md) · [All operations](https://skmtc.dev/kernel/apis/kernel-images-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kernel/kernel-images-api/revisions/7a641fa15a85/schema)