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

# Swipe

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

Performs a swipe in the specified direction

## Path parameters

- `boxId` string, required

## Request body

- union
  - SwipeSimple — Simple swipe action configuration. The gesture will be performed from the center of the screen towards the specified direction.
    - `direction` 'up' | 'down' | 'left' | 'right' | 'upLeft' | 'upRight' | 'downLeft' | 'downRight', required — Direction to swipe. The gesture will be performed from the center of the screen towards this direction.
    - `duration` string — Duration of the swipe Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 500ms
    - `distance` union — Distance of the swipe. Can be either a number (in pixels) or a predefined enum value (tiny, short, medium, long). If not provided, the swipe will be performed from the center of the screen to the screen edge
      - number
      - 'tiny' | 'short' | 'medium' | 'long'
    - `location` string — Natural language description of the location where the swipe should originate. If not provided, the swipe will be performed from the center of the screen.
    - `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.
  - SwipeAdvanced — Swipe action configuration. The gesture will start from the specified start point and move towards the end point.
    - `start` union, required — Start point of the swipe path (coordinates or natural language)
      - SwipePath — Swipe path
        - `x` number, required — Start/end x coordinate of the swipe path
        - `y` number, required — Start/end y coordinate of the swipe path
      - string
    - `end` union, required — End point of the swipe path (coordinates or natural language)
      - SwipePath — Swipe path
        - `x` number, required — Start/end x coordinate of the swipe path
        - `y` number, required — Start/end y coordinate of the swipe path
      - string
    - `duration` string — Duration of the swipe 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`

Swipe action result with actual parameters used

- SwipeActionResult — Result of swipe 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` SwipeActionActual, required — Actual parameters used when executing the swipe action
    - `start` SwipePath, required — Swipe path
      - `x` number, required — Start/end x coordinate of the swipe path
      - `y` number, required — Start/end y coordinate of the swipe path
    - `end` SwipePath, required — Swipe path
      - `x` number, required — Start/end x coordinate of the swipe path
      - `y` number, required — Start/end y coordinate of the swipe path
    - `duration` string, required — Duration of the swipe Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 500ms

## Changes

- **2025-12-02** `d655577fa915` — 4 info
  - the `model` request property default value changed from `ui-tars` to `gelato`
  - the `model` request property default value changed from `ui-tars` to `gelato`
  - added the new `gelato` enum value to the request property `oneOf[subschema #1: Swipe Simple]/options/allOf[subschema #1: Action Common Options]/model`
  - added the new `gelato` enum value to the request property `oneOf[subschema #2: Swipe Advanced]/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` — 2 warning, 2 info
  - removed the request property `oneOf[subschema #1: Swipe Simple]/model`
  - removed the request property `oneOf[subschema #2: Swipe Advanced]/model`
  - added the new optional request property `oneOf[subschema #1: Swipe Simple]/options/allOf[subschema #1: Action Common Options]/model`
  - added the new optional request property `oneOf[subschema #2: Swipe Advanced]/options/allOf[subschema #1: Action Common Options]/model`
- **2025-09-30** `625e86264c1f` — 2 info
  - added the new optional request property `oneOf[subschema #1: Swipe Simple]/model`
  - added the new optional request property `oneOf[subschema #2: Swipe Advanced]/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/swipe/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)