---
title: "Press button"
method: POST
path: "/boxes/{boxId}/actions/press-button"
tags: ["UI Action"]
---

# Press button

`POST /boxes/{boxId}/actions/press-button`

Press device buttons like power, volume, home, back, etc.

## Path parameters

- `boxId` string, required

## Request body

- PressButton — Press button action configuration
  - `buttons` string[], required — Button to press
  - `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`

- ActionResult — Result of an UI action execution with optional screenshots
  - `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

## 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-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/press-button/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)