---
title: "Rotate screen"
method: POST
path: "/boxes/{boxId}/actions/screen-rotation"
tags: ["UI Action"]
---

# Rotate screen

`POST /boxes/{boxId}/actions/screen-rotation`

Rotates the screen orientation. Note that even after rotating the screen, applications or system layouts may not automatically adapt to the gravity sensor changes, so visual changes may not always occur.

## Path parameters

- `boxId` string, required

## Request body

- ScreenRotation — Screen rotation parameters
  - `orientation` 'portrait' | 'landscapeLeft' | 'portraitUpsideDown' | 'landscapeRight', required — Target screen orientation
  - `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/screen-rotation/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)