Drag

Simulates a drag gesture, moving from a start point to an end point over a set duration. Supports simple start/end coordinates, multi-point drag paths, and natural-language targets.

POST /boxes/{boxId}/actions/drag

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" });

  await box.action.drag({
    start: { x: 100, y: 150 },
    end: { x: 200, y: 200 },
    duration: "50ms"
  });

  // Natural language start/end 
  await box.action.drag({
    start: "Chrome App",
    end: "Trash",
    duration: "800ms"
  });

  await box.action.drag({
    path: [
      { x: 100, y: 150 },
      { x: 200, y: 200 },
      { x: 300, y: 250 }
    ],
    duration: "50ms"
  });
}

main();

import os
from gbox_sdk import GboxSDK


def main():
    gbox_sdk = GboxSDK(api_key=os.environ["GBOX_API_KEY"])

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

    # Drag action (advanced path)
    box.action.drag(
        path=[
            {"x": 100, "y": 150},
            {"x": 200, "y": 200},
            {"x": 300, "y": 250}
        ],
        duration="50ms"
    )

    # Drag action (simple coordinates)
    box.action.drag(
        start={"x": 100, "y": 150},
        end={"x": 200, "y": 200},
        duration="50ms"
    )

    # Drag action (natural language, realistic Android example)
    # Drag the "Chrome" app icon to the launcher "Remove" target at the top bar
    box.action.drag(
        start="Chrome",
        end="Remove",
        duration="800ms"
    )


if __name__ == "__main__":
    main()

curl --request POST \
  --url https://gbox.ai/api/v1/boxes/{boxId}/actions/drag \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "start": {
    "x": 100,
    "y": 100
  },
  "end": {
    "x": 200,
    "y": 200
  }
}
'

200

{
  "message": "Action executed successfully",
  "actionId": "c9bdc193-b54b-4ddb-a035-5ac0c598d32d",
  "actual": {
    "start": {
      "x": 100,
      "y": 150
    },
    "end": {
      "x": 400,
      "y": 300
    },
    "duration": "500ms"
  },
  "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

Drag Simple

Drag Advanced

Drag action configuration with start and end points.

Operation flow:

1. Touch finger at "start" coordinates
2. Move to "end" coordinates within the "duration" time and lift finger

start · Drag Path Point · object string · required

Start point of the drag path (coordinates or natural language)

Show child attributes

Example:

{ "x": 100, "y": 150 }

end · Drag Path Point · object string · required

End point of the drag path (coordinates or natural language)

Show child attributes

Example:

{ "x": 400, "y": 300 }

duration · string · default: 500ms

Duration to complete the movement from start to end coordinates

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: "500ms", "30s", "5m", "1h" Default: 500ms

Example:

"500ms"

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

Drag action result with actual parameters used

Result of drag action execution with actual parameters used

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"

actual · Drag Action Actual Parameters · object · required

Actual parameters used when executing the drag action

Show child attributes

Example:

{
  "start": { "x": 100, "y": 150 },
  "end": { "x": 400, "y": 300 },
  "duration": "500ms"
}

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..."
  }
}