gbox_sdk.resources.v1.boxes package¶
Submodules¶
gbox_sdk.resources.v1.boxes.actions module¶
- class gbox_sdk.resources.v1.boxes.actions.ActionsResource(client)¶
Bases:
SyncAPIResource- click(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, button=<gbox_sdk.Omit object>, double=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- clipboard_get(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the clipboard content
- Return type:
str
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- clipboard_set(box_id, *, content, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Set the clipboard content
- Return type:
None
- Args:
content: The content to set the clipboard content
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- drag(box_id, *, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, path=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- elements_detect(box_id, *, screenshot=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Detect and identify interactive UI elements in the current screen.
Note: This feature currently only supports element detection within a running browser. If the browser is not running, the Elements array will be empty.
- Return type:
ActionElementsDetectResponse
- Args:
screenshot: Detect elements screenshot options
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- extract(box_id, *, instruction, schema=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Extract data from the UI interface using a JSON schema.
- Return type:
ActionExtractResponse
- Args:
instruction: The instruction of the action to extract data from the UI interface
- schema: JSON Schema defining the structure of data to extract. Supports object, array,
string, number, boolean types with validation rules.
Common use cases:
Extract text content: { “type”: “string” }
Extract structured data: { “type”: “object”, “properties”: {…} }
Extract lists: { “type”: “array”, “items”: {…} }
Extract with validation: Add constraints like “required”, “enum”, “pattern”, etc.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- long_press(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- move(box_id, *, x, y, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Moves the focus to a specific coordinate on the box without performing a click or tap. Use this endpoint to position the cursor, hover over elements, or prepare for chained actions such as drag or swipe.
- Return type:
ActionResult
- Args:
x: X coordinate to move to
y: Y coordinate to move to
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- press_button(box_id, *, buttons, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Press device buttons like power, volume, home, back, etc.
- Return type:
ActionResult
- Args:
buttons: Button to press
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- press_key(box_id, *, keys, combination=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Simulates pressing a specific key by triggering the complete keyboard key event chain (keydown, keypress, keyup). Use this to activate keyboard key event listeners such as shortcuts or form submissions.
- Return type:
ActionResult
- Args:
- keys: This is an array of keyboard keys to press. Supports cross-platform
compatibility.
- combination: Whether to press keys as combination (simultaneously) or sequentially. When
true, all keys are pressed together as a shortcut (e.g., Ctrl+C). When false, keys are pressed one by one in sequence.
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- recording_start(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Start recording the box screen.
Only one recording can be active at a time. If a recording is already in progress, starting a new recording will stop the previous one and keep only the latest recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- recording_stop(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Stop recording the box screen
- Return type:
ActionRecordingStopResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- rewind_disable(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Disable the device’s background screen rewind recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- rewind_enable(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Enable the device’s background screen rewind recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- rewind_extract(box_id, *, duration=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Rewind and capture the device’s background screen recording from a specified time period.
- Return type:
ActionRewindExtractResponse
- Args:
- duration: How far back in time to rewind for extracting recorded video. This specifies the
duration to go back from the current moment (e.g., ’30s’ rewinds 30 seconds to get recent recorded activity). Default is 30s, max is 5m.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Maximum allowed: 5m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- screen_layout(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the current structured screen layout information.
This endpoint returns detailed structural information about the UI elements currently displayed on the screen, which can be used for UI automation, element analysis, and accessibility purposes. The format varies by box type: Android boxes return XML format with detailed UI hierarchy information including element bounds, text content, resource IDs, and properties, while other box types may return different structured formats.
- Return type:
ActionScreenLayoutResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- screen_rotation(box_id, *, orientation, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
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.
- Return type:
ActionResult
- Args:
orientation: Target screen orientation
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- screenshot(box_id, *, clip=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, save_to_album=<gbox_sdk.Omit object>, scroll_capture=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Captures a screenshot of the current box screen
- Return type:
- Args:
clip: Clipping region for screenshot capture
output_format: Type of the URI. default is base64.
presigned_expires_in: 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
save_to_album: Whether to save the screenshot to the device screenshot album
scroll_capture: Scroll capture parameters
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- scroll(box_id, *, scroll_x=<gbox_sdk.Omit object>, scroll_y=<gbox_sdk.Omit object>, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- settings(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the action settings for the box
- Return type:
ActionSettingsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- settings_reset(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Resets the box settings to default
- Return type:
ActionSettingsResetResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- settings_update(box_id, *, scale, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Update the action settings for the box
- Return type:
ActionSettingsUpdateResponse
- Args:
- scale: The scale of the action to be performed. Must be greater than 0.1 and less than
or equal to 1.
Notes:
Scale does not change the box’s actual screen resolution.
It affects the size of the output screenshot and the coordinates/distances of actions. Coordinates and distances are scaled by this factor. Example: when scale = 1, Click({x:100, y:100}); when scale = 0.5, the equivalent position is Click({x:50, y:50}).
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- swipe(box_id, *, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- tap(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- touch(box_id, *, points, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Performs more advanced touch gestures.
Use this endpoint to simulate realistic behaviors.
- Return type:
ActionResult
- Args:
points: Array of touch points and their actions
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- type(box_id, *, text, include_screenshot=<gbox_sdk.Omit object>, mode=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, press_enter=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Directly inputs text content without triggering physical key events (keydown, etc.), ideal for quickly filling large amounts of text when intermediate input events aren’t needed.
- Return type:
ActionResult
- Args:
text: Text to type
- include_screenshot: ⚠️ 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.
- mode: Text input mode: ‘append’ to add text to existing content, ‘replace’ to replace
all existing text
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
press_enter: Whether to press Enter after typing the text
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: ActionsResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: ActionsResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.actions.AsyncActionsResource(client)¶
Bases:
AsyncAPIResource- click(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, button=<gbox_sdk.Omit object>, double=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async clipboard_get(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the clipboard content
- Return type:
str
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async clipboard_set(box_id, *, content, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Set the clipboard content
- Return type:
None
- Args:
content: The content to set the clipboard content
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- drag(box_id, *, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, path=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async elements_detect(box_id, *, screenshot=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Detect and identify interactive UI elements in the current screen.
Note: This feature currently only supports element detection within a running browser. If the browser is not running, the Elements array will be empty.
- Return type:
ActionElementsDetectResponse
- Args:
screenshot: Detect elements screenshot options
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async extract(box_id, *, instruction, schema=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Extract data from the UI interface using a JSON schema.
- Return type:
ActionExtractResponse
- Args:
instruction: The instruction of the action to extract data from the UI interface
- schema: JSON Schema defining the structure of data to extract. Supports object, array,
string, number, boolean types with validation rules.
Common use cases:
Extract text content: { “type”: “string” }
Extract structured data: { “type”: “object”, “properties”: {…} }
Extract lists: { “type”: “array”, “items”: {…} }
Extract with validation: Add constraints like “required”, “enum”, “pattern”, etc.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- long_press(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async move(box_id, *, x, y, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Moves the focus to a specific coordinate on the box without performing a click or tap. Use this endpoint to position the cursor, hover over elements, or prepare for chained actions such as drag or swipe.
- Return type:
ActionResult
- Args:
x: X coordinate to move to
y: Y coordinate to move to
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async press_button(box_id, *, buttons, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Press device buttons like power, volume, home, back, etc.
- Return type:
ActionResult
- Args:
buttons: Button to press
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async press_key(box_id, *, keys, combination=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Simulates pressing a specific key by triggering the complete keyboard key event chain (keydown, keypress, keyup). Use this to activate keyboard key event listeners such as shortcuts or form submissions.
- Return type:
ActionResult
- Args:
- keys: This is an array of keyboard keys to press. Supports cross-platform
compatibility.
- combination: Whether to press keys as combination (simultaneously) or sequentially. When
true, all keys are pressed together as a shortcut (e.g., Ctrl+C). When false, keys are pressed one by one in sequence.
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async recording_start(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Start recording the box screen.
Only one recording can be active at a time. If a recording is already in progress, starting a new recording will stop the previous one and keep only the latest recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async recording_stop(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Stop recording the box screen
- Return type:
ActionRecordingStopResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async rewind_disable(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Disable the device’s background screen rewind recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async rewind_enable(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Enable the device’s background screen rewind recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async rewind_extract(box_id, *, duration=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Rewind and capture the device’s background screen recording from a specified time period.
- Return type:
ActionRewindExtractResponse
- Args:
- duration: How far back in time to rewind for extracting recorded video. This specifies the
duration to go back from the current moment (e.g., ’30s’ rewinds 30 seconds to get recent recorded activity). Default is 30s, max is 5m.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Maximum allowed: 5m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async screen_layout(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the current structured screen layout information.
This endpoint returns detailed structural information about the UI elements currently displayed on the screen, which can be used for UI automation, element analysis, and accessibility purposes. The format varies by box type: Android boxes return XML format with detailed UI hierarchy information including element bounds, text content, resource IDs, and properties, while other box types may return different structured formats.
- Return type:
ActionScreenLayoutResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async screen_rotation(box_id, *, orientation, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
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.
- Return type:
ActionResult
- Args:
orientation: Target screen orientation
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async screenshot(box_id, *, clip=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, save_to_album=<gbox_sdk.Omit object>, scroll_capture=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Captures a screenshot of the current box screen
- Return type:
- Args:
clip: Clipping region for screenshot capture
output_format: Type of the URI. default is base64.
presigned_expires_in: 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
save_to_album: Whether to save the screenshot to the device screenshot album
scroll_capture: Scroll capture parameters
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- scroll(box_id, *, scroll_x=<gbox_sdk.Omit object>, scroll_y=<gbox_sdk.Omit object>, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async settings(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the action settings for the box
- Return type:
ActionSettingsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async settings_reset(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Resets the box settings to default
- Return type:
ActionSettingsResetResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async settings_update(box_id, *, scale, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Update the action settings for the box
- Return type:
ActionSettingsUpdateResponse
- Args:
- scale: The scale of the action to be performed. Must be greater than 0.1 and less than
or equal to 1.
Notes:
Scale does not change the box’s actual screen resolution.
It affects the size of the output screenshot and the coordinates/distances of actions. Coordinates and distances are scaled by this factor. Example: when scale = 1, Click({x:100, y:100}); when scale = 0.5, the equivalent position is Click({x:50, y:50}).
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- swipe(box_id, *, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- tap(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async touch(box_id, *, points, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Performs more advanced touch gestures.
Use this endpoint to simulate realistic behaviors.
- Return type:
ActionResult
- Args:
points: Array of touch points and their actions
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async type(box_id, *, text, include_screenshot=<gbox_sdk.Omit object>, mode=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, press_enter=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Directly inputs text content without triggering physical key events (keydown, etc.), ideal for quickly filling large amounts of text when intermediate input events aren’t needed.
- Return type:
ActionResult
- Args:
text: Text to type
- include_screenshot: ⚠️ 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.
- mode: Text input mode: ‘append’ to add text to existing content, ‘replace’ to replace
all existing text
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
press_enter: Whether to press Enter after typing the text
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncActionsResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncActionsResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
gbox_sdk.resources.v1.boxes.android module¶
- class gbox_sdk.resources.v1.boxes.android.AndroidResource(client)¶
Bases:
SyncAPIResource- backup(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Backup
- Return type:
BinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- backup_all(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Backup all
- Return type:
BinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- close(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Forces the specified Android application to close inside the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- close_all(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Terminates all running Android applications inside the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get pkg
- Return type:
AndroidPkg
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_app(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get installed app info by package name
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_connect_address(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get connect address
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- install(box_id, *, apk, open=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
- list_activities(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves the list of activities defined in a specific Android package
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list_app(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
List all installed apps on the launcher
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list_pkg(box_id, *, pkg_type=<gbox_sdk.Omit object>, running_filter=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves detailed information for all installed pkgs.
This endpoint provides comprehensive pkg details.
- Return type:
- Args:
pkg_type: system or thirdParty, default is thirdParty
- running_filter: Filter pkgs by running status: running (show only running pkgs), notRunning
(show only non-running pkgs). Default is all
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list_pkg_simple(box_id, *, pkg_type=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
A faster endpoint to quickly retrieve basic pkg information.
This API provides better performance for scenarios where you need to get essential pkg details quickly.
- Return type:
- Args:
pkg_type: system or thirdParty, default is thirdParty
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- open(package_name, *, box_id, activity_name=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Launches a specific Android application within the box
- Return type:
None
- Args:
activity_name: Activity name, default is the main activity.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- restart(package_name, *, box_id, activity_name=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Closes and immediately reopens the specified Android application inside the box
- Return type:
None
- Args:
activity_name: Activity name, default is the main activity.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- restore(box_id, *, backup, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Restore
- Return type:
None
- Args:
backup: Backup file to restore (max file size: 100MB)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- uninstall(package_name, *, box_id, keep_data=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Uninstalls an Android app from the box
- Return type:
None
- Args:
keep_data: uninstalls the pkg while retaining the data/cache
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AndroidResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AndroidResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.android.AsyncAndroidResource(client)¶
Bases:
AsyncAPIResource- async backup(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Backup
- Return type:
AsyncBinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async backup_all(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Backup all
- Return type:
AsyncBinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async close(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Forces the specified Android application to close inside the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async close_all(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Terminates all running Android applications inside the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get pkg
- Return type:
AndroidPkg
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_app(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get installed app info by package name
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_connect_address(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get connect address
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- install(box_id, *, apk, open=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
- async list_activities(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves the list of activities defined in a specific Android package
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list_app(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
List all installed apps on the launcher
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list_pkg(box_id, *, pkg_type=<gbox_sdk.Omit object>, running_filter=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves detailed information for all installed pkgs.
This endpoint provides comprehensive pkg details.
- Return type:
- Args:
pkg_type: system or thirdParty, default is thirdParty
- running_filter: Filter pkgs by running status: running (show only running pkgs), notRunning
(show only non-running pkgs). Default is all
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list_pkg_simple(box_id, *, pkg_type=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
A faster endpoint to quickly retrieve basic pkg information.
This API provides better performance for scenarios where you need to get essential pkg details quickly.
- Return type:
- Args:
pkg_type: system or thirdParty, default is thirdParty
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async open(package_name, *, box_id, activity_name=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Launches a specific Android application within the box
- Return type:
None
- Args:
activity_name: Activity name, default is the main activity.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async restart(package_name, *, box_id, activity_name=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Closes and immediately reopens the specified Android application inside the box
- Return type:
None
- Args:
activity_name: Activity name, default is the main activity.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async restore(box_id, *, backup, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Restore
- Return type:
None
- Args:
backup: Backup file to restore (max file size: 100MB)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async uninstall(package_name, *, box_id, keep_data=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Uninstalls an Android app from the box
- Return type:
None
- Args:
keep_data: uninstalls the pkg while retaining the data/cache
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncAndroidResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncAndroidResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
gbox_sdk.resources.v1.boxes.boxes module¶
- class gbox_sdk.resources.v1.boxes.boxes.AsyncBoxesResource(client)¶
Bases:
AsyncAPIResource- property actions: AsyncActionsResource¶
- property android: AsyncAndroidResource¶
- property browser: AsyncBrowserResource¶
- async create_android(*, config=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Provisions a new Android box that you can operate through the GBOX SDK.
Use this endpoint when you want to create a fresh Android environment for testing, automation, or agent execution.
- Return type:
- Args:
config: Configuration for a Android box instance
- api_timeout: Timeout for waiting the box to transition from pending to running state, default
is 30s. If the box doesn’t reach running state within this timeout, the API will return HTTP status code 408. The timed-out box will be automatically deleted and will not count towards your quota.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s Maximum allowed: 5m
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async create_linux(*, config=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Provisions a new Linux box that you can operate through the GBOX SDK.
Use this endpoint when you want to create a fresh Linux environment for testing, automation, or agent execution.
- Return type:
- Args:
config: Configuration for a Linux box instance
- api_timeout: Timeout for waiting the box to transition from pending to running state, default
is 30s. If the box doesn’t reach running state within this timeout, the API will return HTTP status code 408. The timed-out box will be automatically deleted and will not count towards your quota.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s Maximum allowed: 5m
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async display(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieve the current display properties for a running box.
This endpoint provides details about the box’s screen resolution, orientation, and other visual properties.
- Return type:
BoxDisplayResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async execute_commands(box_id, *, command, envs=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Execute a command on a running box.
This endpoint allows you to send commands to the box and receive the output
- Return type:
- Args:
command: The command to run
envs: The environment variables to run the command
- api_timeout: The timeout of the command. If the command times out, the exit code will be 124.
For example: ‘timeout 5s sleep 10s’ will result in exit code 124.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s
- working_dir: The working directory of the command. It not provided, the command will be run
in the box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property fs: AsyncFsResource¶
- async list(*, device_type=<gbox_sdk.Omit object>, labels=<gbox_sdk.Omit object>, page=<gbox_sdk.Omit object>, page_size=<gbox_sdk.Omit object>, status=<gbox_sdk.Omit object>, type=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Returns a paginated list of box instances.
Use this endpoint to monitor environments, filter by status or type, or retrieve boxes by labels or device type.
- Return type:
- Args:
device_type: Filter boxes by their device type (virtual, physical)
- labels: Filter boxes by their labels. Labels are key-value pairs that help identify and
categorize boxes. Use this to filter boxes that match specific label criteria. For example, you can filter by project, environment, team, or any custom labels you’ve added to your boxes.
page: Page number
page_size: Page size
- status: Filter boxes by their current status (pending, running, stopped, error,
terminated, all). Must be an array of statuses. Use ‘all’ to get boxes with any status.
- type: Filter boxes by their type (linux, android, all). Must be an array of types. Use
‘all’ to get boxes of any type.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async live_view_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the live view of a running box. The URL is valid for a limited time and can be used to view the box’s live stream.
- Return type:
- Args:
expires_in: The live view will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 180m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property media: AsyncMediaResource¶
- property proxy: AsyncProxyResource¶
- async resolution_set(box_id, *, height, width, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Set the screen resolution
- Return type:
BoxResolutionSetResponse
- Args:
height: The height of the screen
width: The width of the screen
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async retrieve(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint retrieves information about a box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async run_code(box_id, *, code, argv=<gbox_sdk.Omit object>, envs=<gbox_sdk.Omit object>, language=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Executes code inside the specified box.
Supports multiple languages (bash, Python, TypeScript) and allows you to configure environment variables, arguments, working directory, and timeouts.
- Return type:
- Args:
code: The code to run
- argv: The arguments to run the code. For example, if you want to run “python index.py
–help”, you should pass [”–help”] as arguments.
envs: The environment variables to run the code
language: The language of the code.
- api_timeout: The timeout of the code execution. If the code execution times out, the exit
code will be 124.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s
- working_dir: The working directory of the code. It not provided, the code will be run in the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async start(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Start box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async stop(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Stop box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property storage: AsyncStorageResource¶
- async terminate(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Terminate a running box.
This action will stop the box and release its resources.
- Return type:
None
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async web_terminal_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the web terminal of a running box. The URL is valid for a limited time and can be used to access the box’s terminal interface.
- Return type:
- Args:
expires_in: The web terminal will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 180m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async websocket_url(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the websocket url for the box.
This endpoint provides the WebSocket URLs for executing shell commands and running code snippets in the box environment. These URLs allow real-time communication and data exchange with the box, enabling interactive terminal sessions and code execution.
- Return type:
BoxWebsocketURLResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncBoxesResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncBoxesResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.boxes.BoxesResource(client)¶
Bases:
SyncAPIResource- property actions: ActionsResource¶
- property android: AndroidResource¶
- property browser: BrowserResource¶
- create_android(*, config=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Provisions a new Android box that you can operate through the GBOX SDK.
Use this endpoint when you want to create a fresh Android environment for testing, automation, or agent execution.
- Return type:
- Args:
config: Configuration for a Android box instance
- api_timeout: Timeout for waiting the box to transition from pending to running state, default
is 30s. If the box doesn’t reach running state within this timeout, the API will return HTTP status code 408. The timed-out box will be automatically deleted and will not count towards your quota.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s Maximum allowed: 5m
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- create_linux(*, config=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Provisions a new Linux box that you can operate through the GBOX SDK.
Use this endpoint when you want to create a fresh Linux environment for testing, automation, or agent execution.
- Return type:
- Args:
config: Configuration for a Linux box instance
- api_timeout: Timeout for waiting the box to transition from pending to running state, default
is 30s. If the box doesn’t reach running state within this timeout, the API will return HTTP status code 408. The timed-out box will be automatically deleted and will not count towards your quota.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s Maximum allowed: 5m
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- display(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieve the current display properties for a running box.
This endpoint provides details about the box’s screen resolution, orientation, and other visual properties.
- Return type:
BoxDisplayResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- execute_commands(box_id, *, command, envs=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Execute a command on a running box.
This endpoint allows you to send commands to the box and receive the output
- Return type:
- Args:
command: The command to run
envs: The environment variables to run the command
- api_timeout: The timeout of the command. If the command times out, the exit code will be 124.
For example: ‘timeout 5s sleep 10s’ will result in exit code 124.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s
- working_dir: The working directory of the command. It not provided, the command will be run
in the box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property fs: FsResource¶
- list(*, device_type=<gbox_sdk.Omit object>, labels=<gbox_sdk.Omit object>, page=<gbox_sdk.Omit object>, page_size=<gbox_sdk.Omit object>, status=<gbox_sdk.Omit object>, type=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Returns a paginated list of box instances.
Use this endpoint to monitor environments, filter by status or type, or retrieve boxes by labels or device type.
- Return type:
- Args:
device_type: Filter boxes by their device type (virtual, physical)
- labels: Filter boxes by their labels. Labels are key-value pairs that help identify and
categorize boxes. Use this to filter boxes that match specific label criteria. For example, you can filter by project, environment, team, or any custom labels you’ve added to your boxes.
page: Page number
page_size: Page size
- status: Filter boxes by their current status (pending, running, stopped, error,
terminated, all). Must be an array of statuses. Use ‘all’ to get boxes with any status.
- type: Filter boxes by their type (linux, android, all). Must be an array of types. Use
‘all’ to get boxes of any type.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- live_view_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the live view of a running box. The URL is valid for a limited time and can be used to view the box’s live stream.
- Return type:
- Args:
expires_in: The live view will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 180m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property media: MediaResource¶
- property proxy: ProxyResource¶
- resolution_set(box_id, *, height, width, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Set the screen resolution
- Return type:
BoxResolutionSetResponse
- Args:
height: The height of the screen
width: The width of the screen
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- retrieve(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint retrieves information about a box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- run_code(box_id, *, code, argv=<gbox_sdk.Omit object>, envs=<gbox_sdk.Omit object>, language=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Executes code inside the specified box.
Supports multiple languages (bash, Python, TypeScript) and allows you to configure environment variables, arguments, working directory, and timeouts.
- Return type:
- Args:
code: The code to run
- argv: The arguments to run the code. For example, if you want to run “python index.py
–help”, you should pass [”–help”] as arguments.
envs: The environment variables to run the code
language: The language of the code.
- api_timeout: The timeout of the code execution. If the code execution times out, the exit
code will be 124.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s
- working_dir: The working directory of the code. It not provided, the code will be run in the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- start(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Start box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- stop(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Stop box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property storage: StorageResource¶
- terminate(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Terminate a running box.
This action will stop the box and release its resources.
- Return type:
None
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- web_terminal_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the web terminal of a running box. The URL is valid for a limited time and can be used to access the box’s terminal interface.
- Return type:
- Args:
expires_in: The web terminal will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 180m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- websocket_url(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the websocket url for the box.
This endpoint provides the WebSocket URLs for executing shell commands and running code snippets in the box environment. These URLs allow real-time communication and data exchange with the box, enabling interactive terminal sessions and code execution.
- Return type:
BoxWebsocketURLResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: BoxesResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: BoxesResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
gbox_sdk.resources.v1.boxes.browser module¶
- class gbox_sdk.resources.v1.boxes.browser.AsyncBrowserResource(client)¶
Bases:
AsyncAPIResource- async cdp_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the Chrome DevTools Protocol (CDP) of a running box. The URL is valid for a limited time and can be used to interact with the box’s browser environment
- Return type:
str
- Args:
expires_in: The CDP url will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 120m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async clear_proxy(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async close(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Close the browser in the specified box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async close_tab(tab_id, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Close a specific browser tab identified by its id.
This endpoint will permanently close the tab and free up the associated resources. After closing a tab, the ids of subsequent tabs may change.
- Return type:
BrowserCloseTabResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_proxy(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
BrowserGetProxyResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_tabs(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieve a comprehensive list of all currently open browser tabs in the specified box. This endpoint returns detailed information about each tab including its id, title, current URL, and favicon. The returned id can be used for subsequent operations like navigation, closing, or updating tabs. This is essential for managing multiple browser sessions and understanding the current state of the browser environment.
- Return type:
BrowserGetTabsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async open(box_id, *, maximize=<gbox_sdk.Omit object>, show_controls=<gbox_sdk.Omit object>, size=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Open the browser in the specified box.
If the browser is already open, repeated calls will not open a new browser.
- Return type:
BrowserOpenResponse
- Args:
maximize: Whether to maximize the browser window.
- show_controls: Whether to show the browser’s minimize, maximize and close buttons. Default is
true.
- size: The window size, format: <width>x<height>. If not specified, the browser will
open with the default size. If both maximize and size are specified, maximize will take precedence.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async open_tab(box_id, *, url, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Create and open a new browser tab with the specified URL.
This endpoint will navigate to the provided URL and return the new tab’s information including its assigned id, loaded title, final URL (after any redirects), and favicon. The returned tab id can be used for future operations on this specific tab. The browser will attempt to load the page and will wait for the DOM content to be loaded before returning the response. If the URL is invalid or unreachable, an error will be returned.
- Return type:
BrowserOpenTabResponse
- Args:
url: The tab url
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async set_proxy(box_id, *, http_server, https_server, socks5_server, bypass_list=<gbox_sdk.Omit object>, pac_url=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
None
- Args:
http_server: HTTP proxy server, format: http://<username>:<password>@<host>:<port>
https_server: HTTPS proxy server, format: https://<username>:<password>@<host>:<port>
socks5_server: SOCKS5 proxy server, format: socks5://<username>:<password>@<host>:<port>
- bypass_list: List of IP addresses and domains that should bypass the proxy. These addresses
will be accessed directly without going through the proxy server. Default is [‘127.0.0.1’, ‘localhost’]
pac_url: PAC (Proxy Auto-Configuration) URL.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async switch_tab(tab_id, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Switch to a specific browser tab by bringing it to the foreground (making it the active/frontmost tab). This operation sets the specified tab as the currently active tab without changing its URL or content. The tab will receive focus and become visible to the user. This is useful for managing multiple browser sessions and controlling which tab is currently in focus.
- Return type:
BrowserSwitchTabResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async update_tab(tab_id, *, box_id, url, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Navigate an existing browser tab to a new URL.
This endpoint updates the specified tab by navigating it to the provided URL and returns the updated tab information. The browser will wait for the DOM content to be loaded before returning the response. If the navigation fails due to an invalid URL or network issues, an error will be returned. The updated tab information will include the new title, final URL (after any redirects), and favicon from the new page.
- Return type:
BrowserUpdateTabResponse
- Args:
url: The tab new url
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncBrowserResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncBrowserResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.browser.BrowserResource(client)¶
Bases:
SyncAPIResource- cdp_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the Chrome DevTools Protocol (CDP) of a running box. The URL is valid for a limited time and can be used to interact with the box’s browser environment
- Return type:
str
- Args:
expires_in: The CDP url will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 120m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- clear_proxy(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- close(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Close the browser in the specified box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- close_tab(tab_id, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Close a specific browser tab identified by its id.
This endpoint will permanently close the tab and free up the associated resources. After closing a tab, the ids of subsequent tabs may change.
- Return type:
BrowserCloseTabResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_proxy(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
BrowserGetProxyResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_tabs(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieve a comprehensive list of all currently open browser tabs in the specified box. This endpoint returns detailed information about each tab including its id, title, current URL, and favicon. The returned id can be used for subsequent operations like navigation, closing, or updating tabs. This is essential for managing multiple browser sessions and understanding the current state of the browser environment.
- Return type:
BrowserGetTabsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- open(box_id, *, maximize=<gbox_sdk.Omit object>, show_controls=<gbox_sdk.Omit object>, size=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Open the browser in the specified box.
If the browser is already open, repeated calls will not open a new browser.
- Return type:
BrowserOpenResponse
- Args:
maximize: Whether to maximize the browser window.
- show_controls: Whether to show the browser’s minimize, maximize and close buttons. Default is
true.
- size: The window size, format: <width>x<height>. If not specified, the browser will
open with the default size. If both maximize and size are specified, maximize will take precedence.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- open_tab(box_id, *, url, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Create and open a new browser tab with the specified URL.
This endpoint will navigate to the provided URL and return the new tab’s information including its assigned id, loaded title, final URL (after any redirects), and favicon. The returned tab id can be used for future operations on this specific tab. The browser will attempt to load the page and will wait for the DOM content to be loaded before returning the response. If the URL is invalid or unreachable, an error will be returned.
- Return type:
BrowserOpenTabResponse
- Args:
url: The tab url
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- set_proxy(box_id, *, http_server, https_server, socks5_server, bypass_list=<gbox_sdk.Omit object>, pac_url=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
None
- Args:
http_server: HTTP proxy server, format: http://<username>:<password>@<host>:<port>
https_server: HTTPS proxy server, format: https://<username>:<password>@<host>:<port>
socks5_server: SOCKS5 proxy server, format: socks5://<username>:<password>@<host>:<port>
- bypass_list: List of IP addresses and domains that should bypass the proxy. These addresses
will be accessed directly without going through the proxy server. Default is [‘127.0.0.1’, ‘localhost’]
pac_url: PAC (Proxy Auto-Configuration) URL.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- switch_tab(tab_id, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Switch to a specific browser tab by bringing it to the foreground (making it the active/frontmost tab). This operation sets the specified tab as the currently active tab without changing its URL or content. The tab will receive focus and become visible to the user. This is useful for managing multiple browser sessions and controlling which tab is currently in focus.
- Return type:
BrowserSwitchTabResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- update_tab(tab_id, *, box_id, url, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Navigate an existing browser tab to a new URL.
This endpoint updates the specified tab by navigating it to the provided URL and returns the updated tab information. The browser will wait for the DOM content to be loaded before returning the response. If the navigation fails due to an invalid URL or network issues, an error will be returned. The updated tab information will include the new title, final URL (after any redirects), and favicon from the new page.
- Return type:
BrowserUpdateTabResponse
- Args:
url: The tab new url
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: BrowserResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: BrowserResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
gbox_sdk.resources.v1.boxes.fs module¶
- class gbox_sdk.resources.v1.boxes.fs.AsyncFsResource(client)¶
Bases:
AsyncAPIResource- async exists(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Check if file/dir exists
- Return type:
Union[ExistsFileResult,NotExistsFileResult]
- Args:
path: Target path in the box.
- If the path does not start with ‘/’, the file/directory
will be checked relative to the working directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async info(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves metadata for a specific file or directory inside a box
- Return type:
Union[File,Dir]
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file/directory
will be checked relative to the working directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list(box_id, *, path, depth=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Lists files and directories in a box.
You can specify the directory path and depth, and optionally a working directory. The response includes metadata such as type, size, permissions, and last modified time.
- Return type:
- Args:
path: Target directory path in the box
depth: Depth of the directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async read(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Reads the contents of a file inside the box and returns it as a string.
Supports absolute or relative paths, with workingDir as the base for relative paths.
- Return type:
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file will be
read from the working directory.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async remove(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Deletes a file or a directory.
If target path doesn’t exist, the delete will fail.
- Return type:
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file/directory
will be deleted relative to the working directory. If the target path does not exist, the delete will fail.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async rename(box_id, *, new_path, old_path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Renames a file or a directory.
If the target newPath already exists, the rename will fail.
- Return type:
Union[File,Dir]
- Args:
- new_path: New path in the box. If the path does not start with ‘/’, the file/directory
will be renamed relative to the working directory. If the newPath already exists, the rename will fail.
- old_path: Old path in the box. If the path does not start with ‘/’, the file/directory
will be renamed relative to the working directory. If the oldPath does not exist, the rename will fail.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncFsResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncFsResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- write(box_id, *, content, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
File
- class gbox_sdk.resources.v1.boxes.fs.FsResource(client)¶
Bases:
SyncAPIResource- exists(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Check if file/dir exists
- Return type:
Union[ExistsFileResult,NotExistsFileResult]
- Args:
path: Target path in the box.
- If the path does not start with ‘/’, the file/directory
will be checked relative to the working directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- info(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves metadata for a specific file or directory inside a box
- Return type:
Union[File,Dir]
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file/directory
will be checked relative to the working directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list(box_id, *, path, depth=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Lists files and directories in a box.
You can specify the directory path and depth, and optionally a working directory. The response includes metadata such as type, size, permissions, and last modified time.
- Return type:
- Args:
path: Target directory path in the box
depth: Depth of the directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- read(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Reads the contents of a file inside the box and returns it as a string.
Supports absolute or relative paths, with workingDir as the base for relative paths.
- Return type:
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file will be
read from the working directory.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- remove(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Deletes a file or a directory.
If target path doesn’t exist, the delete will fail.
- Return type:
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file/directory
will be deleted relative to the working directory. If the target path does not exist, the delete will fail.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- rename(box_id, *, new_path, old_path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Renames a file or a directory.
If the target newPath already exists, the rename will fail.
- Return type:
Union[File,Dir]
- Args:
- new_path: New path in the box. If the path does not start with ‘/’, the file/directory
will be renamed relative to the working directory. If the newPath already exists, the rename will fail.
- old_path: Old path in the box. If the path does not start with ‘/’, the file/directory
will be renamed relative to the working directory. If the oldPath does not exist, the rename will fail.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: FsResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: FsResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- write(box_id, *, content, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
File
Module contents¶
- class gbox_sdk.resources.v1.boxes.ActionsResource(client)¶
Bases:
SyncAPIResource- click(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, button=<gbox_sdk.Omit object>, double=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- clipboard_get(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the clipboard content
- Return type:
str
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- clipboard_set(box_id, *, content, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Set the clipboard content
- Return type:
None
- Args:
content: The content to set the clipboard content
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- drag(box_id, *, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, path=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- elements_detect(box_id, *, screenshot=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Detect and identify interactive UI elements in the current screen.
Note: This feature currently only supports element detection within a running browser. If the browser is not running, the Elements array will be empty.
- Return type:
ActionElementsDetectResponse
- Args:
screenshot: Detect elements screenshot options
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- extract(box_id, *, instruction, schema=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Extract data from the UI interface using a JSON schema.
- Return type:
ActionExtractResponse
- Args:
instruction: The instruction of the action to extract data from the UI interface
- schema: JSON Schema defining the structure of data to extract. Supports object, array,
string, number, boolean types with validation rules.
Common use cases:
Extract text content: { “type”: “string” }
Extract structured data: { “type”: “object”, “properties”: {…} }
Extract lists: { “type”: “array”, “items”: {…} }
Extract with validation: Add constraints like “required”, “enum”, “pattern”, etc.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- long_press(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- move(box_id, *, x, y, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Moves the focus to a specific coordinate on the box without performing a click or tap. Use this endpoint to position the cursor, hover over elements, or prepare for chained actions such as drag or swipe.
- Return type:
ActionResult
- Args:
x: X coordinate to move to
y: Y coordinate to move to
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- press_button(box_id, *, buttons, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Press device buttons like power, volume, home, back, etc.
- Return type:
ActionResult
- Args:
buttons: Button to press
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- press_key(box_id, *, keys, combination=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Simulates pressing a specific key by triggering the complete keyboard key event chain (keydown, keypress, keyup). Use this to activate keyboard key event listeners such as shortcuts or form submissions.
- Return type:
ActionResult
- Args:
- keys: This is an array of keyboard keys to press. Supports cross-platform
compatibility.
- combination: Whether to press keys as combination (simultaneously) or sequentially. When
true, all keys are pressed together as a shortcut (e.g., Ctrl+C). When false, keys are pressed one by one in sequence.
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- recording_start(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Start recording the box screen.
Only one recording can be active at a time. If a recording is already in progress, starting a new recording will stop the previous one and keep only the latest recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- recording_stop(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Stop recording the box screen
- Return type:
ActionRecordingStopResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- rewind_disable(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Disable the device’s background screen rewind recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- rewind_enable(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Enable the device’s background screen rewind recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- rewind_extract(box_id, *, duration=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Rewind and capture the device’s background screen recording from a specified time period.
- Return type:
ActionRewindExtractResponse
- Args:
- duration: How far back in time to rewind for extracting recorded video. This specifies the
duration to go back from the current moment (e.g., ’30s’ rewinds 30 seconds to get recent recorded activity). Default is 30s, max is 5m.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Maximum allowed: 5m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- screen_layout(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the current structured screen layout information.
This endpoint returns detailed structural information about the UI elements currently displayed on the screen, which can be used for UI automation, element analysis, and accessibility purposes. The format varies by box type: Android boxes return XML format with detailed UI hierarchy information including element bounds, text content, resource IDs, and properties, while other box types may return different structured formats.
- Return type:
ActionScreenLayoutResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- screen_rotation(box_id, *, orientation, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
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.
- Return type:
ActionResult
- Args:
orientation: Target screen orientation
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- screenshot(box_id, *, clip=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, save_to_album=<gbox_sdk.Omit object>, scroll_capture=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Captures a screenshot of the current box screen
- Return type:
- Args:
clip: Clipping region for screenshot capture
output_format: Type of the URI. default is base64.
presigned_expires_in: 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
save_to_album: Whether to save the screenshot to the device screenshot album
scroll_capture: Scroll capture parameters
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- scroll(box_id, *, scroll_x=<gbox_sdk.Omit object>, scroll_y=<gbox_sdk.Omit object>, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- settings(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the action settings for the box
- Return type:
ActionSettingsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- settings_reset(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Resets the box settings to default
- Return type:
ActionSettingsResetResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- settings_update(box_id, *, scale, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Update the action settings for the box
- Return type:
ActionSettingsUpdateResponse
- Args:
- scale: The scale of the action to be performed. Must be greater than 0.1 and less than
or equal to 1.
Notes:
Scale does not change the box’s actual screen resolution.
It affects the size of the output screenshot and the coordinates/distances of actions. Coordinates and distances are scaled by this factor. Example: when scale = 1, Click({x:100, y:100}); when scale = 0.5, the equivalent position is Click({x:50, y:50}).
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- swipe(box_id, *, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- tap(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- touch(box_id, *, points, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Performs more advanced touch gestures.
Use this endpoint to simulate realistic behaviors.
- Return type:
ActionResult
- Args:
points: Array of touch points and their actions
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- type(box_id, *, text, include_screenshot=<gbox_sdk.Omit object>, mode=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, press_enter=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Directly inputs text content without triggering physical key events (keydown, etc.), ideal for quickly filling large amounts of text when intermediate input events aren’t needed.
- Return type:
ActionResult
- Args:
text: Text to type
- include_screenshot: ⚠️ 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.
- mode: Text input mode: ‘append’ to add text to existing content, ‘replace’ to replace
all existing text
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
press_enter: Whether to press Enter after typing the text
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: ActionsResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: ActionsResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.ActionsResourceWithRawResponse(actions)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.ActionsResourceWithStreamingResponse(actions)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AndroidResource(client)¶
Bases:
SyncAPIResource- backup(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Backup
- Return type:
BinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- backup_all(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Backup all
- Return type:
BinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- close(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Forces the specified Android application to close inside the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- close_all(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Terminates all running Android applications inside the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get pkg
- Return type:
AndroidPkg
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_app(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get installed app info by package name
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_connect_address(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get connect address
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- install(box_id, *, apk, open=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
- list_activities(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves the list of activities defined in a specific Android package
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list_app(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
List all installed apps on the launcher
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list_pkg(box_id, *, pkg_type=<gbox_sdk.Omit object>, running_filter=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves detailed information for all installed pkgs.
This endpoint provides comprehensive pkg details.
- Return type:
- Args:
pkg_type: system or thirdParty, default is thirdParty
- running_filter: Filter pkgs by running status: running (show only running pkgs), notRunning
(show only non-running pkgs). Default is all
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list_pkg_simple(box_id, *, pkg_type=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
A faster endpoint to quickly retrieve basic pkg information.
This API provides better performance for scenarios where you need to get essential pkg details quickly.
- Return type:
- Args:
pkg_type: system or thirdParty, default is thirdParty
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- open(package_name, *, box_id, activity_name=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Launches a specific Android application within the box
- Return type:
None
- Args:
activity_name: Activity name, default is the main activity.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- restart(package_name, *, box_id, activity_name=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Closes and immediately reopens the specified Android application inside the box
- Return type:
None
- Args:
activity_name: Activity name, default is the main activity.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- restore(box_id, *, backup, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Restore
- Return type:
None
- Args:
backup: Backup file to restore (max file size: 100MB)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- uninstall(package_name, *, box_id, keep_data=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Uninstalls an Android app from the box
- Return type:
None
- Args:
keep_data: uninstalls the pkg while retaining the data/cache
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AndroidResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AndroidResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.AndroidResourceWithRawResponse(android)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AndroidResourceWithStreamingResponse(android)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncActionsResource(client)¶
Bases:
AsyncAPIResource- click(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, button=<gbox_sdk.Omit object>, double=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async clipboard_get(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the clipboard content
- Return type:
str
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async clipboard_set(box_id, *, content, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Set the clipboard content
- Return type:
None
- Args:
content: The content to set the clipboard content
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- drag(box_id, *, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, path=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async elements_detect(box_id, *, screenshot=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Detect and identify interactive UI elements in the current screen.
Note: This feature currently only supports element detection within a running browser. If the browser is not running, the Elements array will be empty.
- Return type:
ActionElementsDetectResponse
- Args:
screenshot: Detect elements screenshot options
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async extract(box_id, *, instruction, schema=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Extract data from the UI interface using a JSON schema.
- Return type:
ActionExtractResponse
- Args:
instruction: The instruction of the action to extract data from the UI interface
- schema: JSON Schema defining the structure of data to extract. Supports object, array,
string, number, boolean types with validation rules.
Common use cases:
Extract text content: { “type”: “string” }
Extract structured data: { “type”: “object”, “properties”: {…} }
Extract lists: { “type”: “array”, “items”: {…} }
Extract with validation: Add constraints like “required”, “enum”, “pattern”, etc.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- long_press(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async move(box_id, *, x, y, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Moves the focus to a specific coordinate on the box without performing a click or tap. Use this endpoint to position the cursor, hover over elements, or prepare for chained actions such as drag or swipe.
- Return type:
ActionResult
- Args:
x: X coordinate to move to
y: Y coordinate to move to
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async press_button(box_id, *, buttons, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Press device buttons like power, volume, home, back, etc.
- Return type:
ActionResult
- Args:
buttons: Button to press
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async press_key(box_id, *, keys, combination=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Simulates pressing a specific key by triggering the complete keyboard key event chain (keydown, keypress, keyup). Use this to activate keyboard key event listeners such as shortcuts or form submissions.
- Return type:
ActionResult
- Args:
- keys: This is an array of keyboard keys to press. Supports cross-platform
compatibility.
- combination: Whether to press keys as combination (simultaneously) or sequentially. When
true, all keys are pressed together as a shortcut (e.g., Ctrl+C). When false, keys are pressed one by one in sequence.
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async recording_start(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Start recording the box screen.
Only one recording can be active at a time. If a recording is already in progress, starting a new recording will stop the previous one and keep only the latest recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async recording_stop(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Stop recording the box screen
- Return type:
ActionRecordingStopResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async rewind_disable(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Disable the device’s background screen rewind recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async rewind_enable(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Enable the device’s background screen rewind recording.
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async rewind_extract(box_id, *, duration=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Rewind and capture the device’s background screen recording from a specified time period.
- Return type:
ActionRewindExtractResponse
- Args:
- duration: How far back in time to rewind for extracting recorded video. This specifies the
duration to go back from the current moment (e.g., ’30s’ rewinds 30 seconds to get recent recorded activity). Default is 30s, max is 5m.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Maximum allowed: 5m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async screen_layout(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the current structured screen layout information.
This endpoint returns detailed structural information about the UI elements currently displayed on the screen, which can be used for UI automation, element analysis, and accessibility purposes. The format varies by box type: Android boxes return XML format with detailed UI hierarchy information including element bounds, text content, resource IDs, and properties, while other box types may return different structured formats.
- Return type:
ActionScreenLayoutResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async screen_rotation(box_id, *, orientation, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
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.
- Return type:
ActionResult
- Args:
orientation: Target screen orientation
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async screenshot(box_id, *, clip=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, save_to_album=<gbox_sdk.Omit object>, scroll_capture=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Captures a screenshot of the current box screen
- Return type:
- Args:
clip: Clipping region for screenshot capture
output_format: Type of the URI. default is base64.
presigned_expires_in: 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
save_to_album: Whether to save the screenshot to the device screenshot album
scroll_capture: Scroll capture parameters
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- scroll(box_id, *, scroll_x=<gbox_sdk.Omit object>, scroll_y=<gbox_sdk.Omit object>, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async settings(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the action settings for the box
- Return type:
ActionSettingsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async settings_reset(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Resets the box settings to default
- Return type:
ActionSettingsResetResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async settings_update(box_id, *, scale, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Update the action settings for the box
- Return type:
ActionSettingsUpdateResponse
- Args:
- scale: The scale of the action to be performed. Must be greater than 0.1 and less than
or equal to 1.
Notes:
Scale does not change the box’s actual screen resolution.
It affects the size of the output screenshot and the coordinates/distances of actions. Coordinates and distances are scaled by this factor. Example: when scale = 1, Click({x:100, y:100}); when scale = 0.5, the equivalent position is Click({x:50, y:50}).
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- swipe(box_id, *, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- tap(box_id, *, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
ActionResult
- async touch(box_id, *, points, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Performs more advanced touch gestures.
Use this endpoint to simulate realistic behaviors.
- Return type:
ActionResult
- Args:
points: Array of touch points and their actions
- include_screenshot: ⚠️ 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.
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async type(box_id, *, text, include_screenshot=<gbox_sdk.Omit object>, mode=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, press_enter=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Directly inputs text content without triggering physical key events (keydown, etc.), ideal for quickly filling large amounts of text when intermediate input events aren’t needed.
- Return type:
ActionResult
- Args:
text: Text to type
- include_screenshot: ⚠️ 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.
- mode: Text input mode: ‘append’ to add text to existing content, ‘replace’ to replace
all existing text
options: Action common options
- output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.
default is base64. This field will be ignored when options.screenshot is provided.
- presigned_expires_in: ⚠️ 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
press_enter: Whether to press Enter after typing the text
- screenshot_delay: ⚠️ 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:
Take screenshot before action
Perform the action
Wait for screenshotDelay (this parameter)
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
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncActionsResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncActionsResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.AsyncActionsResourceWithRawResponse(actions)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncActionsResourceWithStreamingResponse(actions)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncAndroidResource(client)¶
Bases:
AsyncAPIResource- async backup(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Backup
- Return type:
AsyncBinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async backup_all(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Backup all
- Return type:
AsyncBinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async close(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Forces the specified Android application to close inside the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async close_all(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Terminates all running Android applications inside the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get pkg
- Return type:
AndroidPkg
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_app(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get installed app info by package name
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_connect_address(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get connect address
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- install(box_id, *, apk, open=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
- async list_activities(package_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves the list of activities defined in a specific Android package
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list_app(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
List all installed apps on the launcher
- Return type:
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list_pkg(box_id, *, pkg_type=<gbox_sdk.Omit object>, running_filter=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves detailed information for all installed pkgs.
This endpoint provides comprehensive pkg details.
- Return type:
- Args:
pkg_type: system or thirdParty, default is thirdParty
- running_filter: Filter pkgs by running status: running (show only running pkgs), notRunning
(show only non-running pkgs). Default is all
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list_pkg_simple(box_id, *, pkg_type=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
A faster endpoint to quickly retrieve basic pkg information.
This API provides better performance for scenarios where you need to get essential pkg details quickly.
- Return type:
- Args:
pkg_type: system or thirdParty, default is thirdParty
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async open(package_name, *, box_id, activity_name=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Launches a specific Android application within the box
- Return type:
None
- Args:
activity_name: Activity name, default is the main activity.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async restart(package_name, *, box_id, activity_name=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Closes and immediately reopens the specified Android application inside the box
- Return type:
None
- Args:
activity_name: Activity name, default is the main activity.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async restore(box_id, *, backup, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Restore
- Return type:
None
- Args:
backup: Backup file to restore (max file size: 100MB)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async uninstall(package_name, *, box_id, keep_data=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Uninstalls an Android app from the box
- Return type:
None
- Args:
keep_data: uninstalls the pkg while retaining the data/cache
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncAndroidResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncAndroidResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.AsyncAndroidResourceWithRawResponse(android)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncAndroidResourceWithStreamingResponse(android)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncBoxesResource(client)¶
Bases:
AsyncAPIResource- property actions: AsyncActionsResource¶
- property android: AsyncAndroidResource¶
- property browser: AsyncBrowserResource¶
- async create_android(*, config=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Provisions a new Android box that you can operate through the GBOX SDK.
Use this endpoint when you want to create a fresh Android environment for testing, automation, or agent execution.
- Return type:
- Args:
config: Configuration for a Android box instance
- api_timeout: Timeout for waiting the box to transition from pending to running state, default
is 30s. If the box doesn’t reach running state within this timeout, the API will return HTTP status code 408. The timed-out box will be automatically deleted and will not count towards your quota.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s Maximum allowed: 5m
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async create_linux(*, config=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Provisions a new Linux box that you can operate through the GBOX SDK.
Use this endpoint when you want to create a fresh Linux environment for testing, automation, or agent execution.
- Return type:
- Args:
config: Configuration for a Linux box instance
- api_timeout: Timeout for waiting the box to transition from pending to running state, default
is 30s. If the box doesn’t reach running state within this timeout, the API will return HTTP status code 408. The timed-out box will be automatically deleted and will not count towards your quota.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s Maximum allowed: 5m
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async display(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieve the current display properties for a running box.
This endpoint provides details about the box’s screen resolution, orientation, and other visual properties.
- Return type:
BoxDisplayResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async execute_commands(box_id, *, command, envs=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Execute a command on a running box.
This endpoint allows you to send commands to the box and receive the output
- Return type:
- Args:
command: The command to run
envs: The environment variables to run the command
- api_timeout: The timeout of the command. If the command times out, the exit code will be 124.
For example: ‘timeout 5s sleep 10s’ will result in exit code 124.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s
- working_dir: The working directory of the command. It not provided, the command will be run
in the box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property fs: AsyncFsResource¶
- async list(*, device_type=<gbox_sdk.Omit object>, labels=<gbox_sdk.Omit object>, page=<gbox_sdk.Omit object>, page_size=<gbox_sdk.Omit object>, status=<gbox_sdk.Omit object>, type=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Returns a paginated list of box instances.
Use this endpoint to monitor environments, filter by status or type, or retrieve boxes by labels or device type.
- Return type:
- Args:
device_type: Filter boxes by their device type (virtual, physical)
- labels: Filter boxes by their labels. Labels are key-value pairs that help identify and
categorize boxes. Use this to filter boxes that match specific label criteria. For example, you can filter by project, environment, team, or any custom labels you’ve added to your boxes.
page: Page number
page_size: Page size
- status: Filter boxes by their current status (pending, running, stopped, error,
terminated, all). Must be an array of statuses. Use ‘all’ to get boxes with any status.
- type: Filter boxes by their type (linux, android, all). Must be an array of types. Use
‘all’ to get boxes of any type.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async live_view_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the live view of a running box. The URL is valid for a limited time and can be used to view the box’s live stream.
- Return type:
- Args:
expires_in: The live view will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 180m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property media: AsyncMediaResource¶
- property proxy: AsyncProxyResource¶
- async resolution_set(box_id, *, height, width, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Set the screen resolution
- Return type:
BoxResolutionSetResponse
- Args:
height: The height of the screen
width: The width of the screen
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async retrieve(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint retrieves information about a box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async run_code(box_id, *, code, argv=<gbox_sdk.Omit object>, envs=<gbox_sdk.Omit object>, language=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Executes code inside the specified box.
Supports multiple languages (bash, Python, TypeScript) and allows you to configure environment variables, arguments, working directory, and timeouts.
- Return type:
- Args:
code: The code to run
- argv: The arguments to run the code. For example, if you want to run “python index.py
–help”, you should pass [”–help”] as arguments.
envs: The environment variables to run the code
language: The language of the code.
- api_timeout: The timeout of the code execution. If the code execution times out, the exit
code will be 124.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s
- working_dir: The working directory of the code. It not provided, the code will be run in the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async start(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Start box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async stop(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Stop box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property storage: AsyncStorageResource¶
- async terminate(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Terminate a running box.
This action will stop the box and release its resources.
- Return type:
None
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async web_terminal_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the web terminal of a running box. The URL is valid for a limited time and can be used to access the box’s terminal interface.
- Return type:
- Args:
expires_in: The web terminal will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 180m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async websocket_url(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the websocket url for the box.
This endpoint provides the WebSocket URLs for executing shell commands and running code snippets in the box environment. These URLs allow real-time communication and data exchange with the box, enabling interactive terminal sessions and code execution.
- Return type:
BoxWebsocketURLResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncBoxesResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncBoxesResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.AsyncBoxesResourceWithRawResponse(boxes)¶
Bases:
object- property actions: AsyncActionsResourceWithRawResponse¶
- property android: AsyncAndroidResourceWithRawResponse¶
- property browser: AsyncBrowserResourceWithRawResponse¶
- property fs: AsyncFsResourceWithRawResponse¶
- property media: AsyncMediaResourceWithRawResponse¶
- property proxy: AsyncProxyResourceWithRawResponse¶
- property storage: AsyncStorageResourceWithRawResponse¶
- class gbox_sdk.resources.v1.boxes.AsyncBoxesResourceWithStreamingResponse(boxes)¶
Bases:
object- property actions: AsyncActionsResourceWithStreamingResponse¶
- property android: AsyncAndroidResourceWithStreamingResponse¶
- property browser: AsyncBrowserResourceWithStreamingResponse¶
- property fs: AsyncFsResourceWithStreamingResponse¶
- property media: AsyncMediaResourceWithStreamingResponse¶
- property proxy: AsyncProxyResourceWithStreamingResponse¶
- property storage: AsyncStorageResourceWithStreamingResponse¶
- class gbox_sdk.resources.v1.boxes.AsyncBrowserResource(client)¶
Bases:
AsyncAPIResource- async cdp_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the Chrome DevTools Protocol (CDP) of a running box. The URL is valid for a limited time and can be used to interact with the box’s browser environment
- Return type:
str
- Args:
expires_in: The CDP url will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 120m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async clear_proxy(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async close(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Close the browser in the specified box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async close_tab(tab_id, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Close a specific browser tab identified by its id.
This endpoint will permanently close the tab and free up the associated resources. After closing a tab, the ids of subsequent tabs may change.
- Return type:
BrowserCloseTabResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_proxy(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
BrowserGetProxyResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_tabs(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieve a comprehensive list of all currently open browser tabs in the specified box. This endpoint returns detailed information about each tab including its id, title, current URL, and favicon. The returned id can be used for subsequent operations like navigation, closing, or updating tabs. This is essential for managing multiple browser sessions and understanding the current state of the browser environment.
- Return type:
BrowserGetTabsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async open(box_id, *, maximize=<gbox_sdk.Omit object>, show_controls=<gbox_sdk.Omit object>, size=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Open the browser in the specified box.
If the browser is already open, repeated calls will not open a new browser.
- Return type:
BrowserOpenResponse
- Args:
maximize: Whether to maximize the browser window.
- show_controls: Whether to show the browser’s minimize, maximize and close buttons. Default is
true.
- size: The window size, format: <width>x<height>. If not specified, the browser will
open with the default size. If both maximize and size are specified, maximize will take precedence.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async open_tab(box_id, *, url, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Create and open a new browser tab with the specified URL.
This endpoint will navigate to the provided URL and return the new tab’s information including its assigned id, loaded title, final URL (after any redirects), and favicon. The returned tab id can be used for future operations on this specific tab. The browser will attempt to load the page and will wait for the DOM content to be loaded before returning the response. If the URL is invalid or unreachable, an error will be returned.
- Return type:
BrowserOpenTabResponse
- Args:
url: The tab url
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async set_proxy(box_id, *, http_server, https_server, socks5_server, bypass_list=<gbox_sdk.Omit object>, pac_url=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
None
- Args:
http_server: HTTP proxy server, format: http://<username>:<password>@<host>:<port>
https_server: HTTPS proxy server, format: https://<username>:<password>@<host>:<port>
socks5_server: SOCKS5 proxy server, format: socks5://<username>:<password>@<host>:<port>
- bypass_list: List of IP addresses and domains that should bypass the proxy. These addresses
will be accessed directly without going through the proxy server. Default is [‘127.0.0.1’, ‘localhost’]
pac_url: PAC (Proxy Auto-Configuration) URL.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async switch_tab(tab_id, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Switch to a specific browser tab by bringing it to the foreground (making it the active/frontmost tab). This operation sets the specified tab as the currently active tab without changing its URL or content. The tab will receive focus and become visible to the user. This is useful for managing multiple browser sessions and controlling which tab is currently in focus.
- Return type:
BrowserSwitchTabResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async update_tab(tab_id, *, box_id, url, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Navigate an existing browser tab to a new URL.
This endpoint updates the specified tab by navigating it to the provided URL and returns the updated tab information. The browser will wait for the DOM content to be loaded before returning the response. If the navigation fails due to an invalid URL or network issues, an error will be returned. The updated tab information will include the new title, final URL (after any redirects), and favicon from the new page.
- Return type:
BrowserUpdateTabResponse
- Args:
url: The tab new url
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncBrowserResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncBrowserResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.AsyncBrowserResourceWithRawResponse(browser)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncBrowserResourceWithStreamingResponse(browser)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncFsResource(client)¶
Bases:
AsyncAPIResource- async exists(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Check if file/dir exists
- Return type:
Union[ExistsFileResult,NotExistsFileResult]
- Args:
path: Target path in the box.
- If the path does not start with ‘/’, the file/directory
will be checked relative to the working directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async info(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves metadata for a specific file or directory inside a box
- Return type:
Union[File,Dir]
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file/directory
will be checked relative to the working directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list(box_id, *, path, depth=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Lists files and directories in a box.
You can specify the directory path and depth, and optionally a working directory. The response includes metadata such as type, size, permissions, and last modified time.
- Return type:
- Args:
path: Target directory path in the box
depth: Depth of the directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async read(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Reads the contents of a file inside the box and returns it as a string.
Supports absolute or relative paths, with workingDir as the base for relative paths.
- Return type:
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file will be
read from the working directory.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async remove(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Deletes a file or a directory.
If target path doesn’t exist, the delete will fail.
- Return type:
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file/directory
will be deleted relative to the working directory. If the target path does not exist, the delete will fail.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async rename(box_id, *, new_path, old_path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Renames a file or a directory.
If the target newPath already exists, the rename will fail.
- Return type:
Union[File,Dir]
- Args:
- new_path: New path in the box. If the path does not start with ‘/’, the file/directory
will be renamed relative to the working directory. If the newPath already exists, the rename will fail.
- old_path: Old path in the box. If the path does not start with ‘/’, the file/directory
will be renamed relative to the working directory. If the oldPath does not exist, the rename will fail.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncFsResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncFsResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- write(box_id, *, content, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
File
- class gbox_sdk.resources.v1.boxes.AsyncFsResourceWithRawResponse(fs)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncFsResourceWithStreamingResponse(fs)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncMediaResource(client)¶
Bases:
AsyncAPIResource- async create_album(box_id, *, name, media=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Create a new album with media files
- Return type:
MediaAlbum
- Args:
name: Name of the album to create
media: Media files to include in the album (max size: 512MB per file)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async delete_album(album_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Delete an album and all its media files
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async delete_media(media_name, *, box_id, album_name, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Delete a specific media file from an album
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async download_media(media_name, *, box_id, album_name, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Download a specific media file from an album
- Return type:
AsyncBinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_album_detail(album_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get detailed information about a specific album including its media files
- Return type:
MediaAlbum
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_media(media_name, *, box_id, album_name, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get detailed information about a specific media file
- Return type:
Union[MediaPhoto,MediaVideo]
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get_media_support(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get supported media file extensions for photos and videos
- Return type:
MediaGetMediaSupportResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list_albums(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get a list of albums in the box
- Return type:
MediaListAlbumsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async list_media(album_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get a list of media files in a specific album
- Return type:
MediaListMediaResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async update_album(album_name, *, box_id, media, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Add media files to an existing album
- Return type:
MediaAlbum
- Args:
media: Media files to add to the album (max size: 512MB per file)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncMediaResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncMediaResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.AsyncMediaResourceWithRawResponse(media)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncMediaResourceWithStreamingResponse(media)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncProxyResource(client)¶
Bases:
AsyncAPIResource- async clear(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Clears the HTTP proxy for the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async get(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves the HTTP proxy settings for a specific box.
Use this endpoint to route traffic through the box’s network.
- Return type:
ProxyGetResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- async set(box_id, *, host, port, auth=<gbox_sdk.Omit object>, excludes=<gbox_sdk.Omit object>, pac_url=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Configures the HTTP proxy settings for a specific box.
Use this endpoint when you need the box’s outbound network traffic to pass through a proxy server.
- Return type:
ProxySetResponse
- Args:
host: The host address of the proxy server
port: The port number of the proxy server
auth: Box Proxy Auth
- excludes: List of IP addresses and domains that should bypass the proxy. These addresses
will be accessed directly without going through the proxy server. Default is [‘127.0.0.1’, ‘localhost’]
pac_url: PAC (Proxy Auto-Configuration) URL.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncProxyResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncProxyResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.AsyncProxyResourceWithRawResponse(proxy)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncProxyResourceWithStreamingResponse(proxy)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncStorageResource(client)¶
Bases:
AsyncAPIResource- async presigned_url(box_id, *, storage_key, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Create a presigned url for a storage key.
This endpoint provides a presigned url for a storage key, which can be used to download the file from the storage.
- Return type:
str
- Args:
storage_key: Storage key
expires_in: Presigned url expires in
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m Maximum allowed: 6h
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: AsyncStorageResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: AsyncStorageResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.AsyncStorageResourceWithRawResponse(storage)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.AsyncStorageResourceWithStreamingResponse(storage)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.BoxesResource(client)¶
Bases:
SyncAPIResource- property actions: ActionsResource¶
- property android: AndroidResource¶
- property browser: BrowserResource¶
- create_android(*, config=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Provisions a new Android box that you can operate through the GBOX SDK.
Use this endpoint when you want to create a fresh Android environment for testing, automation, or agent execution.
- Return type:
- Args:
config: Configuration for a Android box instance
- api_timeout: Timeout for waiting the box to transition from pending to running state, default
is 30s. If the box doesn’t reach running state within this timeout, the API will return HTTP status code 408. The timed-out box will be automatically deleted and will not count towards your quota.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s Maximum allowed: 5m
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- create_linux(*, config=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Provisions a new Linux box that you can operate through the GBOX SDK.
Use this endpoint when you want to create a fresh Linux environment for testing, automation, or agent execution.
- Return type:
- Args:
config: Configuration for a Linux box instance
- api_timeout: Timeout for waiting the box to transition from pending to running state, default
is 30s. If the box doesn’t reach running state within this timeout, the API will return HTTP status code 408. The timed-out box will be automatically deleted and will not count towards your quota.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s Maximum allowed: 5m
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- display(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieve the current display properties for a running box.
This endpoint provides details about the box’s screen resolution, orientation, and other visual properties.
- Return type:
BoxDisplayResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- execute_commands(box_id, *, command, envs=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Execute a command on a running box.
This endpoint allows you to send commands to the box and receive the output
- Return type:
- Args:
command: The command to run
envs: The environment variables to run the command
- api_timeout: The timeout of the command. If the command times out, the exit code will be 124.
For example: ‘timeout 5s sleep 10s’ will result in exit code 124.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s
- working_dir: The working directory of the command. It not provided, the command will be run
in the box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property fs: FsResource¶
- list(*, device_type=<gbox_sdk.Omit object>, labels=<gbox_sdk.Omit object>, page=<gbox_sdk.Omit object>, page_size=<gbox_sdk.Omit object>, status=<gbox_sdk.Omit object>, type=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Returns a paginated list of box instances.
Use this endpoint to monitor environments, filter by status or type, or retrieve boxes by labels or device type.
- Return type:
- Args:
device_type: Filter boxes by their device type (virtual, physical)
- labels: Filter boxes by their labels. Labels are key-value pairs that help identify and
categorize boxes. Use this to filter boxes that match specific label criteria. For example, you can filter by project, environment, team, or any custom labels you’ve added to your boxes.
page: Page number
page_size: Page size
- status: Filter boxes by their current status (pending, running, stopped, error,
terminated, all). Must be an array of statuses. Use ‘all’ to get boxes with any status.
- type: Filter boxes by their type (linux, android, all). Must be an array of types. Use
‘all’ to get boxes of any type.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- live_view_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the live view of a running box. The URL is valid for a limited time and can be used to view the box’s live stream.
- Return type:
- Args:
expires_in: The live view will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 180m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property media: MediaResource¶
- property proxy: ProxyResource¶
- resolution_set(box_id, *, height, width, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Set the screen resolution
- Return type:
BoxResolutionSetResponse
- Args:
height: The height of the screen
width: The width of the screen
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- retrieve(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint retrieves information about a box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- run_code(box_id, *, code, argv=<gbox_sdk.Omit object>, envs=<gbox_sdk.Omit object>, language=<gbox_sdk.Omit object>, api_timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Executes code inside the specified box.
Supports multiple languages (bash, Python, TypeScript) and allows you to configure environment variables, arguments, working directory, and timeouts.
- Return type:
- Args:
code: The code to run
- argv: The arguments to run the code. For example, if you want to run “python index.py
–help”, you should pass [”–help”] as arguments.
envs: The environment variables to run the code
language: The language of the code.
- api_timeout: The timeout of the code execution. If the code execution times out, the exit
code will be 124.
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s
- working_dir: The working directory of the code. It not provided, the code will be run in the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- start(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Start box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- stop(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Stop box
- Return type:
Union[LinuxBox,AndroidBox]
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property storage: StorageResource¶
- terminate(box_id, *, wait=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Terminate a running box.
This action will stop the box and release its resources.
- Return type:
None
- Args:
wait: Wait for the box operation to be completed, default is true
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- web_terminal_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the web terminal of a running box. The URL is valid for a limited time and can be used to access the box’s terminal interface.
- Return type:
- Args:
expires_in: The web terminal will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 180m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- websocket_url(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get the websocket url for the box.
This endpoint provides the WebSocket URLs for executing shell commands and running code snippets in the box environment. These URLs allow real-time communication and data exchange with the box, enabling interactive terminal sessions and code execution.
- Return type:
BoxWebsocketURLResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: BoxesResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: BoxesResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.BoxesResourceWithRawResponse(boxes)¶
Bases:
object- property actions: ActionsResourceWithRawResponse¶
- property android: AndroidResourceWithRawResponse¶
- property browser: BrowserResourceWithRawResponse¶
- property fs: FsResourceWithRawResponse¶
- property media: MediaResourceWithRawResponse¶
- property proxy: ProxyResourceWithRawResponse¶
- property storage: StorageResourceWithRawResponse¶
- class gbox_sdk.resources.v1.boxes.BoxesResourceWithStreamingResponse(boxes)¶
Bases:
object- property actions: ActionsResourceWithStreamingResponse¶
- property android: AndroidResourceWithStreamingResponse¶
- property browser: BrowserResourceWithStreamingResponse¶
- property fs: FsResourceWithStreamingResponse¶
- property media: MediaResourceWithStreamingResponse¶
- property proxy: ProxyResourceWithStreamingResponse¶
- property storage: StorageResourceWithStreamingResponse¶
- class gbox_sdk.resources.v1.boxes.BrowserResource(client)¶
Bases:
SyncAPIResource- cdp_url(box_id, *, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
This endpoint allows you to generate a pre-signed URL for accessing the Chrome DevTools Protocol (CDP) of a running box. The URL is valid for a limited time and can be used to interact with the box’s browser environment
- Return type:
str
- Args:
expires_in: The CDP url will be alive for the given duration
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 120m
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- clear_proxy(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- close(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Close the browser in the specified box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- close_tab(tab_id, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Close a specific browser tab identified by its id.
This endpoint will permanently close the tab and free up the associated resources. After closing a tab, the ids of subsequent tabs may change.
- Return type:
BrowserCloseTabResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_proxy(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
BrowserGetProxyResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_tabs(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieve a comprehensive list of all currently open browser tabs in the specified box. This endpoint returns detailed information about each tab including its id, title, current URL, and favicon. The returned id can be used for subsequent operations like navigation, closing, or updating tabs. This is essential for managing multiple browser sessions and understanding the current state of the browser environment.
- Return type:
BrowserGetTabsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- open(box_id, *, maximize=<gbox_sdk.Omit object>, show_controls=<gbox_sdk.Omit object>, size=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Open the browser in the specified box.
If the browser is already open, repeated calls will not open a new browser.
- Return type:
BrowserOpenResponse
- Args:
maximize: Whether to maximize the browser window.
- show_controls: Whether to show the browser’s minimize, maximize and close buttons. Default is
true.
- size: The window size, format: <width>x<height>. If not specified, the browser will
open with the default size. If both maximize and size are specified, maximize will take precedence.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- open_tab(box_id, *, url, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Create and open a new browser tab with the specified URL.
This endpoint will navigate to the provided URL and return the new tab’s information including its assigned id, loaded title, final URL (after any redirects), and favicon. The returned tab id can be used for future operations on this specific tab. The browser will attempt to load the page and will wait for the DOM content to be loaded before returning the response. If the URL is invalid or unreachable, an error will be returned.
- Return type:
BrowserOpenTabResponse
- Args:
url: The tab url
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- set_proxy(box_id, *, http_server, https_server, socks5_server, bypass_list=<gbox_sdk.Omit object>, pac_url=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
None
- Args:
http_server: HTTP proxy server, format: http://<username>:<password>@<host>:<port>
https_server: HTTPS proxy server, format: https://<username>:<password>@<host>:<port>
socks5_server: SOCKS5 proxy server, format: socks5://<username>:<password>@<host>:<port>
- bypass_list: List of IP addresses and domains that should bypass the proxy. These addresses
will be accessed directly without going through the proxy server. Default is [‘127.0.0.1’, ‘localhost’]
pac_url: PAC (Proxy Auto-Configuration) URL.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- switch_tab(tab_id, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Switch to a specific browser tab by bringing it to the foreground (making it the active/frontmost tab). This operation sets the specified tab as the currently active tab without changing its URL or content. The tab will receive focus and become visible to the user. This is useful for managing multiple browser sessions and controlling which tab is currently in focus.
- Return type:
BrowserSwitchTabResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- update_tab(tab_id, *, box_id, url, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Navigate an existing browser tab to a new URL.
This endpoint updates the specified tab by navigating it to the provided URL and returns the updated tab information. The browser will wait for the DOM content to be loaded before returning the response. If the navigation fails due to an invalid URL or network issues, an error will be returned. The updated tab information will include the new title, final URL (after any redirects), and favicon from the new page.
- Return type:
BrowserUpdateTabResponse
- Args:
url: The tab new url
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: BrowserResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: BrowserResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.BrowserResourceWithRawResponse(browser)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.BrowserResourceWithStreamingResponse(browser)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.FsResource(client)¶
Bases:
SyncAPIResource- exists(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Check if file/dir exists
- Return type:
Union[ExistsFileResult,NotExistsFileResult]
- Args:
path: Target path in the box.
- If the path does not start with ‘/’, the file/directory
will be checked relative to the working directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- info(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves metadata for a specific file or directory inside a box
- Return type:
Union[File,Dir]
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file/directory
will be checked relative to the working directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list(box_id, *, path, depth=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Lists files and directories in a box.
You can specify the directory path and depth, and optionally a working directory. The response includes metadata such as type, size, permissions, and last modified time.
- Return type:
- Args:
path: Target directory path in the box
depth: Depth of the directory
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- read(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Reads the contents of a file inside the box and returns it as a string.
Supports absolute or relative paths, with workingDir as the base for relative paths.
- Return type:
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file will be
read from the working directory.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- remove(box_id, *, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Deletes a file or a directory.
If target path doesn’t exist, the delete will fail.
- Return type:
- Args:
- path: Target path in the box. If the path does not start with ‘/’, the file/directory
will be deleted relative to the working directory. If the target path does not exist, the delete will fail.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- rename(box_id, *, new_path, old_path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Renames a file or a directory.
If the target newPath already exists, the rename will fail.
- Return type:
Union[File,Dir]
- Args:
- new_path: New path in the box. If the path does not start with ‘/’, the file/directory
will be renamed relative to the working directory. If the newPath already exists, the rename will fail.
- old_path: Old path in the box. If the path does not start with ‘/’, the file/directory
will be renamed relative to the working directory. If the oldPath does not exist, the rename will fail.
- working_dir: Working directory. If not provided, the file will be read from the
box.config.workingDir directory.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: FsResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: FsResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- write(box_id, *, content, path, working_dir=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
- Return type:
File
- class gbox_sdk.resources.v1.boxes.FsResourceWithRawResponse(fs)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.FsResourceWithStreamingResponse(fs)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.MediaResource(client)¶
Bases:
SyncAPIResource- create_album(box_id, *, name, media=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Create a new album with media files
- Return type:
MediaAlbum
- Args:
name: Name of the album to create
media: Media files to include in the album (max size: 512MB per file)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- delete_album(album_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Delete an album and all its media files
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- delete_media(media_name, *, box_id, album_name, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Delete a specific media file from an album
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- download_media(media_name, *, box_id, album_name, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Download a specific media file from an album
- Return type:
BinaryAPIResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_album_detail(album_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get detailed information about a specific album including its media files
- Return type:
MediaAlbum
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_media(media_name, *, box_id, album_name, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get detailed information about a specific media file
- Return type:
Union[MediaPhoto,MediaVideo]
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get_media_support(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get supported media file extensions for photos and videos
- Return type:
MediaGetMediaSupportResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list_albums(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get a list of albums in the box
- Return type:
MediaListAlbumsResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- list_media(album_name, *, box_id, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Get a list of media files in a specific album
- Return type:
MediaListMediaResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- update_album(album_name, *, box_id, media, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Add media files to an existing album
- Return type:
MediaAlbum
- Args:
media: Media files to add to the album (max size: 512MB per file)
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: MediaResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: MediaResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.MediaResourceWithRawResponse(media)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.MediaResourceWithStreamingResponse(media)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.ProxyResource(client)¶
Bases:
SyncAPIResource- clear(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Clears the HTTP proxy for the box
- Return type:
None
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- get(box_id, *, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Retrieves the HTTP proxy settings for a specific box.
Use this endpoint to route traffic through the box’s network.
- Return type:
ProxyGetResponse
- Args:
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- set(box_id, *, host, port, auth=<gbox_sdk.Omit object>, excludes=<gbox_sdk.Omit object>, pac_url=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Configures the HTTP proxy settings for a specific box.
Use this endpoint when you need the box’s outbound network traffic to pass through a proxy server.
- Return type:
ProxySetResponse
- Args:
host: The host address of the proxy server
port: The port number of the proxy server
auth: Box Proxy Auth
- excludes: List of IP addresses and domains that should bypass the proxy. These addresses
will be accessed directly without going through the proxy server. Default is [‘127.0.0.1’, ‘localhost’]
pac_url: PAC (Proxy Auto-Configuration) URL.
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: ProxyResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: ProxyResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.ProxyResourceWithRawResponse(proxy)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.ProxyResourceWithStreamingResponse(proxy)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.StorageResource(client)¶
Bases:
SyncAPIResource- presigned_url(box_id, *, storage_key, expires_in=<gbox_sdk.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)¶
Create a presigned url for a storage key.
This endpoint provides a presigned url for a storage key, which can be used to download the file from the storage.
- Return type:
str
- Args:
storage_key: Storage key
expires_in: Presigned url expires in
Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m Maximum allowed: 6h
extra_headers: Send extra headers
extra_query: Add additional query parameters to the request
extra_body: Add additional JSON properties to the request
timeout: Override the client-level default timeout for this request, in seconds
- property with_raw_response: StorageResourceWithRawResponse¶
This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#accessing-raw-response-data-eg-headers
- property with_streaming_response: StorageResourceWithStreamingResponse¶
An alternative to .with_raw_response that doesn’t eagerly read the response body.
For more information, see https://www.github.com/babelcloud/gbox-sdk-py#with_streaming_response
- class gbox_sdk.resources.v1.boxes.StorageResourceWithRawResponse(storage)¶
Bases:
object
- class gbox_sdk.resources.v1.boxes.StorageResourceWithStreamingResponse(storage)¶
Bases:
object