Rotate screen

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.

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

JavaScript

JavaScript

import GboxSDK from "gbox-sdk";

const gboxSDK = new GboxSDK({
  apiKey: process.env["GBOX_API_KEY"] // This is the default and can be omitted
});

async function main() {
  const box = await gboxSDK.create({ type: "android" });

  // Get current display state including orientation
  const currentDisplay = await box.display();
  console.log("Current orientation:", currentDisplay.orientation);

  // Rotate to landscape left (90 degrees)
  await box.action.screenRotation({
    orientation: "landscapeLeft"
  });

  // Check the new orientation
  const newDisplay = await box.display();
  console.log("New orientation:", newDisplay.orientation);

  // Rotate to portrait upside down (180 degrees)
  await box.action.screenRotation({
    orientation: "portraitUpsideDown"
  });
}

main();

import os
from gbox_sdk import GboxSDK

def main():
    gbox_sdk = GboxSDK(api_key=os.environ["GBOX_API_KEY"])  # This is the default and can be omitted

    # Create Android box
    box = gbox_sdk.create(type="android")

    # Get current display state including orientation
    current_display = box.display()
    print(f"Current orientation: {current_display.orientation}")

    # Rotate to landscape left (90 degrees)
    box.action.screen_rotation(orientation="landscapeLeft")

    # Check the new orientation
    new_display = box.display()
    print(f"New orientation: {new_display.orientation}")

    # Rotate to portrait upside down (180 degrees)
    box.action.screen_rotation(orientation="portraitUpsideDown")

if __name__ == "__main__":
    main()

curl --request POST \
  --url https://gbox.ai/api/v1/boxes/{boxId}/actions/screen-rotation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "orientation": "landscapeLeft"
}
'

200

{
  "message": "Action executed successfully",
  "actionId": "c9bdc193-b54b-4ddb-a035-5ac0c598d32d",
  "screenshot": {
    "trace": {
      "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
    },
    "before": {
      "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
    },
    "after": {
      "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
    }
  }
}

Authorizations

Authorization · string · header · required

Enter your API Key in the format: Bearer . Get it from https://gbox.ai

Path Parameters

boxId · string · required

Box ID

Example:

"c9bdc193-b54b-4ddb-a035-5ac0c598d32d"

Body

application/json

Screen rotation parameters

orientation · enum<string> · required

Target screen orientation

Available options: portrait, landscapeLeft, portraitUpsideDown, landscapeRight

Example:

"landscapeLeft"

options · Action Common Options · object

Action options. When options.screenshot is provided, ALL deprecated screenshot fields (outputFormat, presignedExpiresIn, screenshotDelay, screenshotRange, includeScreenshot) will be completely ignored.

Show child attributes

Example:

{
  "screenshot": {
    "outputFormat": "base64",
    "presignedExpiresIn": "30m",
    "delay": "500ms",
    "phases": ["before", "after"]
  }
}

Response

200 - application/json

Result of an UI action execution with optional screenshots

message · string · required

message

Example:

"Action executed successfully"

actionId · string · required

Unique identifier for each action. Use this ID to locate the action and report issues.

Example:

"c9bdc193-b54b-4ddb-a035-5ac0c598d32d"

screenshot · Action Result Screenshot · object

Optional screenshot data. Only present when screenshots are requested via options.screenshot.phases or deprecated fields

Show child attributes

Example:

{
  "trace": {
    "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
  },
  "before": {
    "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
  },
  "after": {
    "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
  }
}