--- title: "Click" method: POST path: "/boxes/{boxId}/actions/click" tags: ["UI Action"] --- # Click `POST /boxes/{boxId}/actions/click` Simulates a click action on the box. ## Path parameters - `boxId` string, required ## Request body - union - Click — Mouse click action configuration - `button` 'left' | 'right' | 'middle' — Mouse button to click - `double` boolean — Whether to perform a double click - `modifierKeys` string[] — Modifier keys to hold while performing the click (e.g., control, shift, alt). Supports the same key values as the pressKey action. - `x` number, required — X coordinate of the click - `y` number, required — Y coordinate of the click - `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. - ClickByNaturalLanguage — Click action configuration with natural language - `button` 'left' | 'right' | 'middle' — Mouse button to click - `double` boolean — Whether to perform a double click - `modifierKeys` string[] — Modifier keys to hold while performing the click (e.g., control, shift, alt). Supports the same key values as the pressKey action. - `target` string, required — Describe the target to operate using natural language, e.g., 'login button' or 'Chrome'. - `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. - ClickByElement — Click action configuration by element - `button` 'left' | 'right' | 'middle' — Mouse button to click - `double` boolean — Whether to perform a double click - `modifierKeys` string[] — Modifier keys to hold while performing the click (e.g., control, shift, alt). Supports the same key values as the pressKey action. - `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. - `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` Click action executed successfully. The response includes the actual coordinates where the click was performed, which is especially useful when using natural language targeting. - ClickActionResult — Result of click action execution with actual parameters used. The actual field shows the exact parameters used when performing the click, which is especially useful when using natural language or element-based targeting to understand exactly what action was performed. - `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` ClickActionActual, required — Actual parameters used when executing the click action, with the same field names as input parameters - `x` number, required — X coordinate where the click was executed - `y` number, required — Y coordinate where the click was executed - `button` 'left' | 'right' | 'middle', required — Mouse button that was clicked - `double` boolean, required — Whether a double click was performed - `modifierKeys` string[] — Modifier keys that were pressed during the click (e.g., control, shift, alt). Matches the KeyboardKey enum used by pressKey action. ## 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: Click Action]/options/allOf[subschema #1: Action Common Options]/model` - …2 more - **2025-11-11** `fa6b9650f821` — 4 info - added the new optional request property `oneOf[subschema #1: Click Action]/modifierKeys` - added the new optional request property `oneOf[subschema #2: Click Action with Natural Language]/modifierKeys` - added the new optional request property `oneOf[subschema #3: Click Action by Element]/modifierKeys` - added the optional property `actual/allOf[subschema #1: Click Action Actual Parameters]/modifierKeys` to the response with the `200` status - **2025-11-04** `34ade2db86f7` — 1 info - added the required property `actual` to the response with the `200` status - …earlier changes not shown [Full history](https://skmtc.dev/babelcloud/apis/gbox-open-api/changes/boxes/:boxId/actions/click/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)