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

# Drag

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

Simulates a drag gesture, moving from a start point to an end point over a set duration. Supports simple start/end coordinates, multi-point drag paths, and natural-language targets.

## Path parameters

- `boxId` string, required

## Request body

- union
  - DragSimple — Drag action configuration with start and end points. Operation flow: 1. Touch finger at "start" coordinates 2. Move to "end" coordinates within the "duration" time and lift finger
    - `start` union, required — Start point of the drag path (coordinates or natural language)
      - DragPathPoint — Single point in a drag path
        - `x` number, required — X coordinate of a point in the drag path
        - `y` number, required — Y coordinate of a point in the drag path
      - string
    - `end` union, required — End point of the drag path (coordinates or natural language)
      - DragPathPoint — Single point in a drag path
        - `x` number, required — X coordinate of a point in the drag path
        - `y` number, required — Y coordinate of a point in the drag path
      - string
    - `duration` string — Duration to complete the movement from start to end coordinates 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.
  - DragAdvanced — Drag action configuration with path points
    - `path` DragPathPoint[], required — Path of the drag action as a series of coordinates
      - `x` number, required — X coordinate of a point in the drag path
      - `y` number, required — Y coordinate of a point in the drag path
    - `duration` string — Time interval between points (e.g. "50ms") Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 50ms
    - `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`

Drag action result with actual parameters used

- DragActionResult — Result of drag 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` DragActionActual, required — Actual parameters used when executing the drag action
    - `start` DragPathPoint, required — Single point in a drag path
      - `x` number, required — X coordinate of a point in the drag path
      - `y` number, required — Y coordinate of a point in the drag path
    - `end` DragPathPoint, required — Single point in a drag path
      - `x` number, required — X coordinate of a point in the drag path
      - `y` number, required — Y coordinate of a point in the drag path
    - `duration` string, required — Duration of the drag 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: Drag Simple]/options/allOf[subschema #1: Action Common Options]/model`
  - added the new `gelato` enum value to the request property `oneOf[subschema #2: Drag 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: Drag Simple]/model`
  - removed the request property `oneOf[subschema #2: Drag Advanced]/model`
  - added the new optional request property `oneOf[subschema #1: Drag Simple]/options/allOf[subschema #1: Action Common Options]/model`
  - added the new optional request property `oneOf[subschema #2: Drag Advanced]/options/allOf[subschema #1: Action Common Options]/model`
- **2025-09-30** `625e86264c1f` — 2 info
  - added the new optional request property `oneOf[subschema #1: Drag Simple]/model`
  - added the new optional request property `oneOf[subschema #2: Drag 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/drag/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)