---
title: "Touch"
method: POST
path: "/boxes/{boxId}/actions/touch"
tags: ["UI Action"]
---

# Touch

`POST /boxes/{boxId}/actions/touch`

Performs more advanced touch gestures. Use this endpoint to simulate realistic behaviors.

## Path parameters

- `boxId` string, required

## Request body

- Touch — Multi-touch action configuration
  - `points` TouchPoint[], required — Array of touch points and their actions
    - `start` TouchPointStart, required — Initial touch point position
      - `x` number, required — Starting X coordinate
      - `y` number, required — Starting Y coordinate
    - `actions` union[] — Sequence of actions to perform after initial touch
      - union
        - TouchPointMoveAction — Touch point movement action configuration
          - `type` string, required — Type of the action
          - `x` number, required — Target X coordinate
          - `y` number, required — Target Y coordinate
          - `duration` string, required — Duration of the movement (e.g. "200ms") Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 200ms
        - TouchPointWaitAction — Touch point wait action configuration
          - `type` string, required — Type of the action
          - `duration` string, required — Duration to wait (e.g. "500ms") Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 500ms
  - `options` ActionCommonOptions — Action common options
    - `screenshot` union — Screenshot options. Can be a boolean to enable/disable screenshots, or an object to configure screenshot options.
      - ActionScreenshotOptions — Action screenshot options
        - `outputFormat` 'base64' | 'storageKey' — Type of the URI. default is base64.
        - `presignedExpiresIn` string — Presigned url expires in. Only takes effect when outputFormat is storageKey. Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 30m
        - `delay` string — Delay after performing the action, before taking the final screenshot. Execution flow: 1. Take screenshot before action 2. Perform the action 3. Wait for screenshotDelay (this parameter) 4. Take screenshot after action Example: '500ms' means wait 500ms after the action before capturing the final screenshot. Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 500ms Maximum allowed: 30s
        - `phases` string[] — Specify which screenshot phases to capture. Available options: - before: Screenshot before the action - after: Screenshot after the action - trace: Screenshot with operation trace Default captures all three phases. Can specify one or multiple in an array. If empty array is provided, no screenshots will be taken.
      - boolean
    - `model` 'gpt-5' | 'gpt-4o' | 'gelato' | 'ui-tars' | 'openai-computer-use' — Model to use for natural-language target resolution. Defaults to 'uitars'.
  - `outputFormat` 'base64' | 'storageKey' — ⚠️ DEPRECATED: Use `options.screenshot.outputFormat` instead. Type of the URI. default is base64. This field will be ignored when `options.screenshot` is provided.
  - `presignedExpiresIn` string — ⚠️ DEPRECATED: Use `options.screenshot.presignedExpiresIn` instead. Presigned url expires in. Only takes effect when outputFormat is storageKey. This field will be ignored when `options.screenshot` is provided. Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 30m
  - `screenshotDelay` string — ⚠️ DEPRECATED: Use `options.screenshot.delay` instead. This field will be ignored when `options.screenshot` is provided. Delay after performing the action, before taking the final screenshot. Execution flow: 1. Take screenshot before action 2. Perform the action 3. Wait for screenshotDelay (this parameter) 4. Take screenshot after action Example: '500ms' means wait 500ms after the action before capturing the final screenshot. Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 500ms Maximum allowed: 30s
  - `includeScreenshot` boolean — ⚠️ DEPRECATED: Use `options.screenshot.phases` instead. This field will be ignored when `options.screenshot` is provided. Whether to include screenshots in the action response. If false, the screenshot object will still be returned but with empty URIs. Default is false.

## Response `200`

Touch action result with actual parameters used

- TouchActionResult — Result of touch action execution with actual parameters used
  - `message` string, required — message
  - `actionId` string, required — Unique identifier for each action. Use this ID to locate the action and report issues.
  - `screenshot` ActionResultScreenshot — Complete screenshot result with operation trace, before and after images
    - `trace` ActionResultOperationTrace — Screenshot with action operation trace
      - `uri` string, required — URI of the screenshot with operation trace
    - `before` ActionResultScreenshotBefore — Screenshot taken before action execution
      - `uri` string, required — URI of the screenshot before the action
      - `presignedUrl` string — Presigned url of the screenshot before the action
    - `after` ActionResultScreenshotAfter — Screenshot taken after action execution
      - `uri` string, required — URI of the screenshot after the action
      - `presignedUrl` string — Presigned url of the screenshot before the action
  - `actual` TouchActionActual, required — Actual parameters used when executing the touch action
    - `points` TouchPoint[], required — Array of touch points with their normalized coordinates and actions
      - `start` TouchPointStart, required — Initial touch point position
        - `x` number, required — Starting X coordinate
        - `y` number, required — Starting Y coordinate
      - `actions` union[] — Sequence of actions to perform after initial touch
        - union
          - TouchPointMoveAction — Touch point movement action configuration
            - `type` string, required — Type of the action
            - `x` number, required — Target X coordinate
            - `y` number, required — Target Y coordinate
            - `duration` string, required — Duration of the movement (e.g. "200ms") Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 200ms
          - TouchPointWaitAction — Touch point wait action configuration
            - `type` string, required — Type of the action
            - `duration` string, required — Duration to wait (e.g. "500ms") Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 500ms

## Changes

- **2025-12-02** `d655577fa915` — 2 info
  - the `model` request property default value changed from `ui-tars` to `gelato`
  - added the new `gelato` enum value to the request property `options/allOf[subschema #1: Action Common Options]/model`
- **2025-11-04** `34ade2db86f7` — 1 info
  - added the required property `actual` to the response with the `200` status
- **2025-10-11** `0745319813b5` — 1 warning, 1 info
  - removed the request property `model`
  - added the new optional request property `options/allOf[subschema #1: Action Common Options]/model`
- **2025-09-30** `625e86264c1f` — 1 info
  - added the new optional request property `model`
- **2025-09-16** `edacb8bea21a` — 1 info
  - added the required property `actionId` to the response with the `200` status

[Change history](https://skmtc.dev/babelcloud/apis/gbox-open-api/changes/boxes/:boxId/actions/touch/post.md)

---

[API](https://skmtc.dev/babelcloud/apis/gbox-open-api.md) · [All operations](https://skmtc.dev/babelcloud/apis/gbox-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/babelcloud/gbox-open-api/revisions/d655577fa915/schema)