---
title: "Scroll"
method: POST
path: "/boxes/{boxId}/actions/scroll"
tags: ["UI Action"]
---

# Scroll

`POST /boxes/{boxId}/actions/scroll`

Performs a scroll action. Supports both advanced scroll with coordinates and simple scroll with direction.

## Path parameters

- `boxId` string, required

## Request body

- union
  - ScrollAdvanced — Advanced scroll action configuration. The scroll will be performed from the specified coordinates with the given scroll amounts. Use positive scrollY to scroll content downward (reveal content below), negative scrollY to scroll content upward (reveal content above). Use positive scrollX to scroll content rightward (reveal content on the right), negative scrollX to scroll content leftward (reveal content on the left).
    - `scrollX` number, required — Horizontal scroll amount. Positive values scroll content rightward (reveals content on the right), negative values scroll content leftward (reveals content on the left).
    - `scrollY` number, required — Vertical scroll amount. Positive values scroll content downward (reveals content below), negative values scroll content upward (reveals content above).
    - `x` number, required — X coordinate of the scroll position
    - `y` number, required — Y coordinate of the scroll position
    - `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.
  - ScrollSimple — Simple scroll action configuration. The scroll will be performed from the center of the screen towards the specified direction.
    - `direction` 'up' | 'down' | 'left' | 'right', required — Direction to scroll. The scroll will be performed from the center of the screen towards this direction. 'up' scrolls content upward (reveals content below), 'down' scrolls content downward (reveals content above), 'left' scrolls content leftward (reveals content on the right), 'right' scrolls content rightward (reveals content on the left).
    - `duration` string — Duration of the scroll Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 500ms
    - `distance` union — Distance of the scroll. Can be either a number (in pixels) or a predefined enum value (tiny, short, medium, long). If not provided, the scroll will be performed from the center of the screen to the screen edge
      - number
      - 'tiny' | 'short' | 'medium' | 'long'
    - `location` string — Natural language description of the location where the scroll should originate. If not provided, the scroll will be performed from the center of the screen.
    - `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`

Scroll action result with actual parameters used

- ScrollActionResult — Result of scroll 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` ScrollActionActual, required — Actual parameters used when executing the scroll action
    - `x` number, required — X coordinate of the scroll position
    - `y` number, required — Y coordinate of the scroll position
    - `scrollX` number, required — Horizontal scroll amount
    - `scrollY` number, required — Vertical scroll amount

## Changes

- **2025-12-02** `d655577fa915` — 4 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`
  - added the new `gelato` enum value to the request property `oneOf[subschema #1: Scroll Advanced]/options/allOf[subschema #1: Action Common Options]/model`
  - added the new `gelato` enum value to the request property `oneOf[subschema #2: Scroll Simple]/options/allOf[subschema #1: Action Common Options]/model`
- **2025-11-04** `34ade2db86f7` — 1 info
  - added the required property `actual` to the response with the `200` status
- **2025-10-11** `0745319813b5` — 2 warning, 2 info
  - removed the request property `oneOf[subschema #1: Scroll Advanced]/model`
  - removed the request property `oneOf[subschema #2: Scroll Simple]/model`
  - added the new optional request property `oneOf[subschema #1: Scroll Advanced]/options/allOf[subschema #1: Action Common Options]/model`
  - added the new optional request property `oneOf[subschema #2: Scroll Simple]/options/allOf[subschema #1: Action Common Options]/model`
- **2025-09-30** `625e86264c1f` — 2 info
  - added the new optional request property `oneOf[subschema #1: Scroll Advanced]/model`
  - added the new optional request property `oneOf[subschema #2: Scroll Simple]/model`
- **2025-09-28** `f4c0425f3936` — 1 info
  - added the new optional request property `oneOf[subschema #2: Scroll Simple]/location`

[Full history](https://skmtc.dev/babelcloud/apis/gbox-open-api/changes/boxes/:boxId/actions/scroll/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)