Skip to main content

​
Installation

Install the SDK using pip: 
pip install grasp-sdk

​
Quick Start

from grasp import Grasp

# Initialize the client
grasp = Grasp()

# Create a new container
container = grasp.create()

print(f"CDP Endpoint: {container.browser.ws_endpoint}")

# Shut down the container
container.shutdown()

​
API Reference

​
Grasp(**options)

Initializes the Grasp client.
​
options
dict

​
grasp.create(**options)

Create a new container.
​
options
dict
Returns: GraspContainer Example: 
# Create a container with a 30-second idle timeout
container = grasp.create(idle_timeout=30000)

# Create a container with a proxy
container = grasp.create(
    proxy={
        "enabled": True,
        "type": "residential",
        "country": "US"
    }
)

​
grasp.connect(container_id)

Connect to an existing container. This will wake up the container if it’s sleeping.
​
container_id
str
required
The ID of the container to connect to.
Returns: GraspContainer Example: 
# Connect to an existing container
container = grasp.connect("container-123")

​
GraspContainer

The container object returned by grasp.create() and grasp.connect(). Properties:
​
id
str
Unique container identifier.
​
status
str
Container status.
​
created_at
str
ISO timestamp of creation.
​
browser
BrowserSession
Browser session details.
Methods:

​
container.shutdown()

Stop and clean up the container. Returns: None Example: 
container.shutdown()

​
BrowserSession

Browser session details associated with a container. Properties:
​
ws_endpoint
str
Chrome DevTools Protocol WebSocket endpoint.
​
live_url
str
URL to view the live browser session.
Example: 
cdp_url = container.browser.ws_endpoint
print(f"Connect to: {cdp_url}")

​
Environment Variables

  • GRASP_API_KEY - Default API key (recommended).

​
Error Handling

from grasp import Grasp, GraspError

try:
    grasp = Grasp()
    container = grasp.create()
    # Use container
    container.shutdown()
except GraspError as error:
    print(f"An API error occurred: {error}")

​
Type Hints

The SDK includes full type hints for better IDE support. 
from grasp import Grasp, GraspContainer
from typing import Optional

def create_browser_session(api_key: Optional[str] = None) -> GraspContainer:
    grasp = Grasp(api_key=api_key)
    container = grasp.create()
    return container

​
Using with Playwright

from grasp import Grasp
from playwright.sync_api import sync_playwright

# Initialize the Grasp client
grasp = Grasp()

# Create a new container
container = grasp.create()

# Connect Playwright to the cloud browser
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(container.browser.ws_endpoint)
    page = browser.new_page()
    page.goto("https://example.com")

    # Perform automation
    print(page.title())

    browser.close()

# Clean up
container.shutdown()

​
Async Support

import asyncio
from grasp import AsyncGrasp
from playwright.async_api import async_playwright

async def main():
    # Initialize the async client
    async with AsyncGrasp() as grasp:
        # Create a new container
        container = await grasp.create()

        # Connect Playwright
        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(container.browser.ws_endpoint)
            page = await browser.new_page()
            await page.goto("https://example.com")

            print(await page.title())

            await browser.close()

        # Clean up
        await container.shutdown()

asyncio.run(main())