--- title: "Long press" method: POST path: "/boxes/{boxId}/actions/long-press" tags: ["UI Action"] --- # Long press `POST /boxes/{boxId}/actions/long-press` Perform a long press action at specified coordinates for a specified duration. Useful for triggering context menus, drag operations, or other long-press interactions. ## Path parameters - `boxId` string, required ## Request body - union - LongPress — Long press action configuration. Operation flow: 1. Touch finger at specified coordinates 2. Hold for the specified duration 3. Release finger This is useful for triggering context menus, drag operations, or other long-press interactions. - `x` number, required — X coordinate of the long press - `y` number, required — Y coordinate of the long press - `duration` string — Duration to hold the press (e.g. '1s', '500ms') Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 1s - `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. - LongPressByNaturalLanguage — Long press action configuration using natural language target - `target` string, required — Describe the target to operate using natural language, e.g., 'Chrome icon', 'login button' - `duration` string — Duration to hold the press (e.g. '1s', '500ms') Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 1s - `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. - LongPressByElement — Long press action configuration by element - `target` DetectedElement, required — Detected UI element - `id` string, required — Element id - `source` string, required — Element source - `type` string, required — Element type - `path` string, required — Element path - `width` number, required — Element width - `height` number, required — Element height - `x` number, required — Element x coordinate relative to screen - `y` number, required — Element y coordinate relative to screen - `centerX` number, required — Element center x coordinate relative to screen - `centerY` number, required — Element center y coordinate relative to screen - `label` string, required — A human-readable identifier generated from the element's visible attributes to help understand what this element represents. For images, it uses alt text or filename; for links, it uses text content or href; for buttons, it uses text content or aria-label; for inputs, it uses placeholder or value; etc. - `duration` string — Duration to hold the press (e.g. '1s', '500ms') Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 1s - `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` Long press action executed successfully. The response includes the actual coordinates and duration of the long press. - LongPressActionResult — Result of long press 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` LongPressActionActual, required — Actual parameters used when executing the long press action - `x` number, required — X coordinate where the long press was executed - `y` number, required — Y coordinate where the long press was executed - `duration` string, required — Duration of the long press Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 1s ## Changes - **2025-12-02** `d655577fa915` — 6 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` - 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: Long Press Action]/options/allOf[subschema #1: Action Common Options]/model` - …2 more - **2025-11-04** `34ade2db86f7` — 1 info - added the required property `actual` to the response with the `200` status - **2025-10-11** `0745319813b5` — 3 warning, 3 info - removed the request property `oneOf[subschema #1: Long Press Action]/model` - removed the request property `oneOf[subschema #2: Long Press Action with Natural Language]/model` - removed the request property `oneOf[subschema #3: Long Press Action by Element]/model` - added the new optional request property `oneOf[subschema #1: Long Press Action]/options/allOf[subschema #1: Action Common Options]/model` - …2 more - **2025-09-30** `625e86264c1f` — 3 info - added the new optional request property `oneOf[subschema #1: Long Press Action]/model` - added the new optional request property `oneOf[subschema #2: Long Press Action with Natural Language]/model` - added the new optional request property `oneOf[subschema #3: Long Press Action by Element]/model` - …earlier changes not shown [Full history](https://skmtc.dev/babelcloud/apis/gbox-open-api/changes/boxes/:boxId/actions/long-press/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)