Smooth

https://docs.smooth.sh
Admin
Smooth is a reliable, fast, and affordable serverless browser agent API designed to autonomously...
Tokens:20,318
Snippets:136
Trust Score:5.8
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install Smooth Python SDK

Source: https://docs.smooth.sh/quickstart

Installs the Smooth.sh Python SDK using pip. This is a prerequisite for using the Python client.

```bash
pip install smooth-py
```

--------------------------------

### Run a Task with Smooth.sh (Python, JavaScript, cURL)

Source: https://docs.smooth.sh/quickstart

Demonstrates how to run a task using Smooth.sh across different programming languages and tools. Requires an API key and specifies the task description. Python example shows client initialization and task execution, while JavaScript and cURL examples use direct API calls.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run("Go to google flights and find the cheapest flight from London to Paris today")

print(f"Live URL: {task.live_url()}")
print(f"Agent response: {task.result()}")
```

```javascript
fetch('https://api2.circlemind.co/api/v1/task/smooth', {
  method: 'POST',
  headers: {
    'apikey': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ 'max_steps': 32, 'task': 'your_task_description' })
})
```

```curl
curl -X POST https://api2.circlemind.co/api/v1/task/smooth \
            -H "apikey: cmzr-YOUR_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"max_steps": 32, "task": "your_task_description"}'
```

--------------------------------

### Launch Task with Python SDK

Source: https://docs.smooth.sh/methods/agent

Launches a browser task using the smooth-py SDK. Requires the 'smooth-py' package to be installed. It takes a task description as input and returns the live URL and the agent's result.

```python
# pip install smooth-py
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run("Go to google flights and find the cheapest flight from London to Paris today")

print(f"Live URL: {task.live_url()}")
print(f"Agent response: {task.result()}")
```

--------------------------------

### POST /task

Source: https://docs.smooth.sh/api-reference/agent/run-task

Creates a new task to be executed by an agent. This endpoint allows for detailed configuration of the task, including the task description, desired response model, starting URL, agent type, and execution parameters.

```APIDOC
## POST /task

### Description
Creates a new task to be executed by an agent. This endpoint allows for detailed configuration of the task, including the task description, desired response model, starting URL, agent type, and execution parameters.

### Method
POST

### Endpoint
https://api.smooth.sh/api/v1/task

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **task** (string) - Required - The task to run.
- **response_model** (object) - Optional - If provided, the JSON schema describing the desired output structure.
- **url** (string or null) - Optional - The starting URL for the task. If not provided, the agent will start from a blank page.
- **metadata** (object) - Optional - A dictionary containing variables or parameters that will be passed to the agent.
- **agent** (string) - Optional - The agent to use for the task. Allowed values: `smooth`. Defaults to `smooth`.
- **max_steps** (integer) - Optional - Maximum number of steps the agent can take (min 2, max 128). Defaults to 32.
- **device** (string) - Optional - Device type for the task. Allowed values: `desktop`, `mobile`. Defaults to `mobile`.
- **allowed_urls** (array of strings) - Optional - List of URL patterns using wildcard syntax (e.g., https://*example.com/*) the agent is allowed to visit. If not provided, the agent can visit any URL.
- **enable_recording** (boolean) - Optional - Enable video recording of the task execution. Defaults to `true`.
- **profile_id** (string or null) - Optional - Browser profile ID to use. Each profile maintains its own state, such as login credentials.
- **profile_read_only** (boolean) - Optional - If true, the profile specified by `profile_id` will be loaded in read-only mode. Changes made during the task will not be saved back to the profile. Defaults to `false`.
- **stealth_mode** (boolean) - Optional - Run the browser in stealth mode. Defaults to `false`.
- **proxy_server** (string or null) - Optional - Proxy server url to route browser traffic through. Must include the protocol to use (e.g. http:// or https://).
- **proxy_username** (string) - Optional - Username for proxy authentication.

### Request Example
```json
{
  "task": "Browse to example.com and extract the page title.",
  "url": "https://example.com",
  "response_model": {
    "type": "object",
    "properties": {
      "page_title": {
        "type": "string"
      }
    }
  },
  "max_steps": 10,
  "device": "desktop"
}
```

### Response
#### Success Response (200)
- **task_id** (string) - The unique identifier for the created task.
- **status** (string) - The initial status of the task (e.g., "pending").

#### Response Example
```json
{
  "task_id": "tsk_abcdef123456",
  "status": "pending"
}
```
```

--------------------------------

### Get Customized Live URL with Python

Source: https://docs.smooth.sh/features/live-share

This Python code snippet shows how to get a customized live URL with interactive and embeddable view options. It initializes the Smooth client, runs a task, and then calls the live_url method with 'interactive=True' and 'embed=True' parameters.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run(
  task="<my-task>",
)

print(f"Live URL: {task.live_url(interactive=True, embed=True)}")
```

--------------------------------

### Execute Lead Capture Task - Python

Source: https://docs.smooth.sh/guides/lead-capture

Initializes the Smooth client with an API key and runs a defined lead capture task. It prints the live URL of the task execution, the extracted output, and the recording URL for review. Dependencies include the 'smooth' library.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")

task = smooth_client.run(
    task=lead_capture_task,
    enable_recording=True
)

print(f"Live URL: {task.live_url()}")
task_result = task.result()
print(f"Agent Response: {task_result.output}")
print(f"Task Video: {task_result.recording_url}")
```

--------------------------------

### Run Task with Uploaded Files

Source: https://docs.smooth.sh/guides/file-uploads

Shows how to execute a task using the `SmoothClient.run()` method, passing the IDs of uploaded files via the `files` parameter. The example demonstrates retrieving the task's live URL, the agent's output, and the task recording URL.

```python
task = smooth_client.run(
    task="Give me an alt text for this image",
    url="https://pallyy.com/tools/alt-text-generator",
    files=[file.id]
)

print(f"Live URL: {task.live_url()}")
task_result = task.result()
print(f"Agent Response: {task_result.output}")
print(f"Task Video: {task_result.recording_url()}")
```

--------------------------------

### POST /run Task API

Source: https://docs.smooth.sh/methods/agent

Launch a browser agent to perform a specific task. This endpoint allows for detailed configuration of the task execution, including output models, starting URLs, metadata, and agent behavior.

```APIDOC
## POST /run

### Description
Launch a browser agent to perform a specified task. This endpoint supports various configurations to control task execution, output format, and agent behavior.

### Method
POST

### Endpoint
/run

### Parameters
#### Request Body
- **task** (string) - Required - The task for the agent to execute.
- **response_model** (dict | BaseModel) - Optional - Enforces a structured output schema. Can be a dictionary describing a JSON schema or a Pydantic Model.
- **url** (string) - Optional - The starting URL for the task. If not provided, the agent will infer it.
- **metadata** (dict) - Optional - A dictionary containing variables or parameters to be passed to the agent.
- **files** (list) - Optional - A list of file IDs to be passed to the agent.
- **agent** (string) - Optional - The agent that will run the task. Currently, only `smooth` is available. Default: `smooth`.
- **max_steps** (int) - Optional - The upper limit on the number of steps the agent can take. Range: 2 to 128. Default: 32.
- **device** (string) - Optional - The type of device for task execution. Choose between `mobile` or `desktop`. Default: `mobile`.
- **allowed_urls** (list) - Optional - List of allowed URL patterns using wildcard syntax. If None, all URLs are allowed.
- **enable_recording** (boolean) - Optional - Toggles the option to record a video of the task execution. Default: True.
- **profile_id** (string) - Optional - The browser profile ID to be utilized. Each profile retains its own state.
- **profile_read_only** (boolean) - Optional - If true, the profile specified by `profile_id` will be loaded in read-only mode. Default: False.
- **stealth_mode** (boolean) - Optional - Activates stealth mode for the browser to help avoid detection. Default: False.
- **proxy_server** (string) - Optional - The hostname or IP address of the proxy server.
- **proxy_username** (string) - Optional - The username for authenticating with the proxy server, if required.
- **proxy_password** (string) - Optional - The password for authenticating with the proxy server, if required.
- **experimental_features** (dict) - Optional - Experimental features to enable for the task.

### Request Example
```json
{
  "task": "Go to google flights and find the cheapest flight from London to Paris today",
  "response_model": {
    "type": "object",
    "properties": {
      "output": {
        "type": "integer",
        "description": "The integer part of the result of the calculation"
      }
    }
  },
  "url": "https://google.com/flights",
  "metadata": {"username": "my_username"},
  "files": ["file_id_1"],
  "agent": "smooth",
  "max_steps": 64,
  "device": "desktop",
  "allowed_urls": ["google.com/*", "*mydomain.com/*"],
  "enable_recording": false,
  "profile_id": "profile_12345",
  "profile_read_only": true,
  "stealth_mode": true,
  "proxy_server": "proxy.example.com",
  "proxy_username": "user123",
  "proxy_password": "password123",
  "experimental_features": {}
}
```

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the launched task.
- **live_url** (string) - The live URL of the browser agent executing the task.
- **result** (any) - The result of the task execution, structured according to `response_model` if provided.

#### Response Example
```json
{
  "task_id": "task_abc123",
  "live_url": "https://smooth.sh/task/abc123",
  "result": {
    "cheapest_flight_price": 150,
    "departure_airport": "LHR",
    "arrival_airport": "CDG"
  }
}
```
```

--------------------------------

### Get Live URL using Python

Source: https://docs.smooth.sh/features/live-share

This Python code snippet demonstrates how to obtain a live URL after running a task using the Smooth client. It initializes the client with an API key and prints the live URL returned by the task.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run(
  task="<my-task>",
)

print(f"Live URL: {task.live_url()}")
```

--------------------------------

### Upload File using Python

Source: https://docs.smooth.sh/api-reference/files/upload-file

This snippet shows how to upload a file using the Smooth.sh Python client. It supports both synchronous and asynchronous operations. You will need to install the `smooth` library and provide your API key.

```python
from smooth import SmoothClient

client = SmoothClient(api_key="YOUR_API_KEY")
with open("/path/to/your/file.txt", "rb") as f:
    upload_response = client.upload_file(f)
print(f"File uploaded with ID: {upload_response.id}")
```

```python
import asyncio
from smooth import SmoothAsyncClient

async def upload_file():
    client = SmoothAsyncClient(api_key="YOUR_API_KEY")
    with open("/path/to/your/file.txt", "rb") as f:
        upload_response = await client.upload_file(f)
    print(f"File uploaded with ID: {upload_response.id}")

asyncio.run(upload_file())
```

--------------------------------

### Enable and Get Video Recording URL (Python)

Source: https://docs.smooth.sh/features/session-recording

This snippet shows how to enable video recording for an agent task and retrieve its URL after completion. It requires the `smooth` library and an API key. The output includes the live URL and the session recording URL.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run(
  task="<my-task>",
  enable_recording=True,
)

print(f"Live URL: {task.live_url()}")
print(f"Session recording URL: {task.recording_url()}")  # Waits for task completion
```

--------------------------------

### Get Task Status using Python (Synchronous)

Source: https://docs.smooth.sh/api-reference/agent/get-task

This example shows how to get a task's status using the Smooth.sh Python SDK in a synchronous manner. It uses an internal method `_get_task` to fetch the status. Note that the SDK's `task_handle.result()` method is recommended for handling task completion polling.

```python
# Note: The SDK's task_handle.result() method handles this polling for
# you.

# This is how you would do it manually:

from smooth import SmoothClient


client = SmoothClient(api_key="YOUR_API_KEY")

task_status = client._get_task("YOUR_TASK_ID") # Internal method

print(task_status)
```

--------------------------------

### Get Task Status using Python (Asynchronous)

Source: https://docs.smooth.sh/api-reference/agent/get-task

This asynchronous Python example demonstrates fetching task status using the Smooth.sh SDK. It utilizes `asyncio` and an internal `_get_task` method. For managing task completion, the `task_handle.result()` method is generally preferred over manual polling.

```python
# Note: The SDK's task_handle.result() method handles this polling for
# you.

# This is how you would do it manually:

import asyncio

from smooth import SmoothAsyncClient


async def check_task():
    client = SmoothAsyncClient(api_key="YOUR_API_KEY")
    task_status = await client._get_task("YOUR_TASK_ID") # Internal method
    print(task_status)
    await client.close()

asyncio.run(check_task())
```

--------------------------------

### Request Specific Output Format - Python

Source: https://docs.smooth.sh/guides/lead-capture

Executes a Smooth task to extract speaker information from a URL, specifying a precise JSON output format. This includes defining the structure for total speakers and individual speaker details (name, title, company), ensuring all fields are present even if empty.

```python
structured_extraction = """
Go to https://london.theaisummit.com/conference-agenda/speakers-2025 and extract speaker information.

Return the data in this exact JSON format:
{
  "total_speakers": <number>,
  "speakers": [
    {
      "name": "Full Name",
      "title": "Job Title",
      "company": "Company Name",
    }
  ]
}

Ensure all fields are included even if empty (use None for missing data).
"""

task = smooth_client.run(
    task=structured_extraction,
    enable_recording=True
)

result = task.result()
speakers_data = result.output

print(speakers_data)
```

--------------------------------

### Open Authenticated Session with Smooth

Source: https://docs.smooth.sh/guides/invoice-retrieval

Initiates a persistent browser session using SmoothClient with a specified profile ID. This is the first step to maintaining login state across tasks. It requires an API key and a profile ID.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
session = smooth_client.open_session(profile_id="calendly-billing")

print(f"Live URL: {session.live_url()}")
print(f"Profile ID: {session.profile_id()}")
```

--------------------------------

### Extract Invoice Details with Smooth

Source: https://docs.smooth.sh/guides/invoice-retrieval

Uses an authenticated Smooth session to navigate to a service's billing page and extract specific invoice information like date and amount. It supports plain text output and enables recording of the task execution. Requires the SmoothClient and a task description.

```python
invoice_task = """
Go to the Calendly billing page and find my most recent invoice.

Extract:
- Invoice date
- Amount paid

Return this information.
"""

task = smooth_client.run(
    task=invoice_task,
    profile_id="calendly-billing",
    enable_recording=True
)

print(f"Live URL: {task.live_url()}")
result = task.result()
print(f"Agent response: {result.output}")
print(f"Task Video: {task.recording_url()}")
```

--------------------------------

### GET /browser/profile

Source: https://docs.smooth.sh/api-reference/profile/list-profiles

Retrieves a list of all browser profiles available for the authenticated user.

```APIDOC
## GET /browser/profile

### Description
Lists all browser profiles for the user.

### Method
GET

### Endpoint
/browser/profile

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **profile_ids** (array[string]) - The IDs of the browser profiles.

#### Response Example
```json
{
  "profile_ids": [
    "<string>"
  ]
}
```
```

--------------------------------

### Get Task Status using JavaScript

Source: https://docs.smooth.sh/api-reference/agent/get-task

This JavaScript code snippet shows how to fetch a task's status from the Smooth.sh API using the `fetch` API. It requires your API key and the task ID. The code includes basic error handling and logs the task status, also indicating if the task is still in progress.

```javascript
const apiKey = 'YOUR_API_KEY';
const taskId = 'YOUR_TASK_ID';
const url = `https://api.smooth.sh/api/v1/task/${taskId}`;

async function getTaskStatus() {
  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'apikey': apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Task status:', data);

    // You can poll this endpoint until status is 'done' or 'failed'
    if (data.r.status === 'running' || data.r.status === 'waiting') {
      console.log('Task is still in progress...');
    }

  } catch (error) {
    console.error('Error fetching task status:', error);
  }
}

getTaskStatus();
```

--------------------------------

### Define Lead Capture Task - Python

Source: https://docs.smooth.sh/guides/lead-capture

Defines a string task for Smooth to extract speaker names and descriptions from a given URL, returning the data in JSON format. This task specifies the data points to collect and the desired output structure.

```python
lead_capture_task = """
Go to https://london.theaisummit.com/conference-agenda/speakers-2025 and extract information about all speakers. 
For each speaker, collect:
- Full name
- Speaker description

Return the data in JSON format as an array of speaker objects.
"""
```

--------------------------------

### GET /websites/smooth_sh

Source: https://docs.smooth.sh/api-reference/session/open-session

Retrieves live stream information including live ID and URL. Handles various error codes for unavailable plans, validation errors, rate limiting, and service unavailability.

```APIDOC
## GET /websites/smooth_sh

### Description
Retrieves live stream information including the live ID and live URL. This endpoint also details potential error responses such as:
- 403: Unavailable on Free Plan or insufficient credits.
- 422: Validation Error.
- 429: Maximum number of concurrent browser sessions reached.
- 503: Service unavailable.

### Method
GET

### Endpoint
/websites/smooth_sh

### Parameters
#### Query Parameters
- **live_id** (string) - Required - The ID of the live stream.
- **live_url** (string) - Required - The URL of the live stream.

### Request Example
```json
{
  "live_id": "<string>",
  "live_url": "<string>"
}
```

### Response
#### Success Response (200)
- **live_id** (string) - The ID of the live stream.
- **live_url** (string) - The URL of the live stream.

#### Response Example
```json
{
  "live_id": "example_live_id",
  "live_url": "https://example.com/live"
}
```

#### Error Responses
- **403** (object) - Unavailable on Free Plan or insufficient credits.
- **422** (object) - Validation Error.
- **429** (object) - Maximum number of concurrent browser sessions reached.
- **503** (object) - Service unavailable. Please try again later.
```

--------------------------------

### Format Invoice Data to JSON with Smooth

Source: https://docs.smooth.sh/guides/invoice-retrieval

Retrieves invoice details from a service's billing page and formats the output into a specified JSON structure. This facilitates easy integration with other systems. It requires the SmoothClient and a detailed task description including the desired JSON schema.

```python
structured_invoice_task = """
Go to my Calendly billing page and get the most recent invoice details.

Return the data in this JSON format:
{
  "invoice_date": "YYYY-MM-DD",
  "amount_paid": 12.00,
  "currency": "USD",
  "payment_method": "Card ending in 1234",
  "billing_period": "January 2025",
  "invoice_number": "INV-123456"
}

Use None for any missing information.
"""

task = smooth_client.run(
    task=structured_invoice_task,
    session_id="calendly-billing"
)

result = task.result()
invoice_data = result.output

print(invoice_data)
```

--------------------------------

### Upload File with Smooth Python Client

Source: https://docs.smooth.sh/features/file-upload

This snippet demonstrates how to upload a file using the Smooth Python client. It requires the 'smooth-py' library to be installed. The uploaded file is represented by a file handle ID which can be used in subsequent tasks. Files are automatically deleted after 24 hours but can be manually deleted.

```python
# pip install smooth-py
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
file_handle = client.upload_file(open("README.md", "rb"))
task = smooth_client.run("Upload the given file to https://www.azurespeed.com/Azure/UploadLargeFile to test the upload speed.", files=[file_handle.id])

...

```

--------------------------------

### Execute SEC Search Task with Smooth Client (Python)

Source: https://docs.smooth.sh/guides/government-portals

Initializes the Smooth client with an API key and executes a predefined task (sec_search_task). It enables recording for the task, prints the live URL for monitoring, retrieves the task's result (extracted output), and provides a URL to the task's recording. This demonstrates the core functionality of running a scraping task via the Smooth client.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")

task = smooth_client.run(
    task=sec_search_task,
    enable_recording=True
)

print(f"Live URL: {task.live_url()}")
task_result = task.result()
print(f"Agent Response: {task_result.output}")
print(f"Task Video: {task.recording_url()}")
```

--------------------------------

### GET /task/{task_id}

Source: https://docs.smooth.sh/api-reference/agent/get-task

Retrieves the status and results of a specific task using its unique identifier.

```APIDOC
## GET /task/{task_id}

### Description
Retrieves the status and results of a specific task using its unique identifier.

### Method
GET

### Endpoint
/task/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the task.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "https://api.smooth.sh/api/v1/task/YOUR_TASK_ID" \
     -H "apikey: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the task.
- **status** (string) - The status of the task. Enum: waiting, running, done, failed, cancelled.
- **output** (any) - The output of the task.
- **credits_used** (integer/null) - The amount of credits used to perform the task.
- **credits_balance** (integer/null) - The amount of credits remaining on the account.
- **device** (string/null) - The device type used for the task. Enum: desktop, mobile.
- **live_url** (string/null) - The live URL for the task output.

#### Response Example
```json
{
  "id": "TASK_ID_EXAMPLE",
  "status": "done",
  "output": {},
  "credits_used": 10,
  "credits_balance": 90,
  "device": "desktop",
  "live_url": "https://example.com/output/TASK_ID_EXAMPLE"
}
```
```

--------------------------------

### Authenticate and Create Task using cURL

Source: https://docs.smooth.sh/api-reference/introduction

This snippet demonstrates how to authenticate with the Smooth.sh API using an API key and send a POST request to create a task. It requires a valid API key and a task description as input.

```curl
curl -X POST https://api2.circlemind.co/api/v1/task \
          -H "apikey: cmzr-YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{"task": "<your_task_description>"}'
```

--------------------------------

### Get Task Status using cURL

Source: https://docs.smooth.sh/api-reference/agent/get-task

This code snippet demonstrates how to retrieve the status of a task using the cURL command-line tool. It requires your API key and the specific task ID you wish to query. This is a direct HTTP request to the Smooth.sh API.

```curl
curl -X GET "https://api.smooth.sh/api/v1/task/YOUR_TASK_ID" \
     -H "apikey: YOUR_API_KEY"
```

--------------------------------

### Execute Flight Search with Smooth Python Client

Source: https://docs.smooth.sh/guides/flight-search

This Python code demonstrates how to execute a flight search task using the SmoothClient. It requires an API key, initializes the client, runs the defined task, and prints the live URL, task result, and recording URL.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")

task = smooth_client.run(
    task=flight_search,
    enable_recording=True
)

print(f"Live URL: {task.live_url()}")
task_result = task.result()
print(f"Agent Response: {task_result.output}")
print(f"Task Video: {task_result.recording_url()}")
```

--------------------------------

### Run Task via Python

Source: https://docs.smooth.sh/api-reference/agent/run-task

This code demonstrates running a task synchronously using the Smooth.sh Python client. It initializes the client with an API key, runs a specified task, and then retrieves the result. Error handling for network issues or API failures is recommended.

```python
from smooth import SmoothClient

client = SmoothClient(api_key="YOUR_API_KEY")

task_handle = client.run(
    task="Go to hacker news and get the top 5 stories.",
    device="desktop",
    max_steps=32
)

print(f"Task ID: {task_handle.id}")
# Wait for the result
result = task_handle.result()
print(result)
```

--------------------------------

### Task Response API

Source: https://docs.smooth.sh/api-reference/agent/get-task

Provides details about the response of a task execution. It includes successful completion responses and accepted responses for ongoing tasks.

```APIDOC
## Task Response Details

### Description
This endpoint provides details about the response of a task execution. It includes successful completion responses and accepted responses for ongoing tasks.

### Method
POST (Implied by context, actual method not specified)

### Endpoint
/websites/smooth_sh (Inferred from project path)

### Parameters
None specified in the provided text.

### Request Example
None specified in the provided text.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the task.
- **status** (string) - The current status of the task (e.g., 'done', 'failed').
- **output** (any) - The output of the task.
- **credits_used** (integer) - The number of credits used by the task.
- **credits_balance** (integer) - The remaining credit balance.
- **device** (string) - The device used for the task (e.g., 'desktop').
- **live_url** (string) - The URL for live interaction with the task.
- **recording_url** (string) - The URL to view the task recording.

#### Response Example (200)
```json
{
  "id": "<string>",
  "status": "waiting",
  "output": null,
  "credits_used": 123,
  "credits_balance": 123,
  "device": "desktop",
  "live_url": "<string>",
  "recording_url": "<string>"
}
```

#### Accepted Response (202)
- **id** (string) - Unique identifier for the task.
- **status** (string) - The current status of the task (e.g., 'waiting', 'running').
- **output** (any) - The output of the task.
- **credits_used** (integer) - The number of credits used by the task.
- **credits_balance** (integer) - The remaining credit balance.
- **device** (string) - The device used for the task (e.g., 'desktop').
- **live_url** (string) - The URL for live interaction with the task.
- **recording_url** (string) - The URL to view the task recording.

#### Response Example (202)
```json
{
  "id": "<string>",
  "status": "waiting",
  "output": null,
  "credits_used": 123,
  "credits_balance": 123,
  "device": "desktop",
  "live_url": "<string>",
  "recording_url": "<string>"
}
```

#### Error Response (422)
- **type** (any) - Indicates a validation error.

#### Response Example (422)
```json
{
  "message": "Validation failed",
  "errors": [
    {
      "field": "example_field",
      "error": "invalid_value"
    }
  ]
}
```
```

--------------------------------

### Run Comprehensive QA Tests - Python

Source: https://docs.smooth.sh/guides/qa-testing

Executes a defined test scenario using the SmoothClient. It enables recording for later analysis and prints the live URL, agent response, and task video URL.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")

task = smooth_client.run(
    task=test_scenario,
    enable_recording=True  # For QA testing, we recommend enabling recording for later analysis
)

print(f"Live URL: {task.live_url()}")
task_result = task.result()
print(f"Agent Response: {task_result.output}")
print(f"Task Video: {task_result.recording_url}")
```

--------------------------------

### Execute and Wait for Task Result (Python)

Source: https://docs.smooth.sh/methods/agent

This Python snippet shows how to initiate a task using the Smooth client, wait for its completion using the `result()` method, and then process the `TaskResponse`. It checks the task status and prints the agent's output or any errors encountered. Dependencies include the `smooth` library.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run("Go to google flights and find the cheapest flight from London to Paris today")

task_result = task.result()  # Waits for the agent response

if task_result.status == "done":
  print(f"Agent response: {task_result.output}")
  print(f"Total cost: ${task_result.credits_used * 0.01}")
else:
  print(f"There was an error: {task_result.error}")
```

--------------------------------

### Run Task API

Source: https://docs.smooth.sh/api-reference/agent/run-task

This endpoint allows you to run a task on a virtual browser. You can specify the task description, device type, and maximum steps.

```APIDOC
## POST /api/v1/task

### Description
Submits a task to be executed on a virtual browser. The task is defined by a natural language description, and execution parameters like device type and maximum steps can be configured.

### Method
POST

### Endpoint
/api/v1/task

### Parameters
#### Query Parameters
None

#### Request Body
- **task** (string) - Required - A natural language description of the task to perform.
- **device** (string) - Optional - The type of device to emulate (e.g., "desktop", "mobile"). Defaults to "desktop".
- **max_steps** (integer) - Optional - The maximum number of steps the task execution is allowed to take. Defaults to 32.
- **enable_recording** (boolean) - Optional - Whether to enable video recording of the task execution. Defaults to false.
- **proxy_username** (string) - Optional - Username for the proxy server.
- **proxy_password** (string) - Optional - Password for the proxy server.
- **experimental_features** (object) - Optional - A dictionary of experimental features to enable or disable.

### Request Example
```json
{
  "task": "Go to hacker news and get the top 5 stories.",
  "device": "desktop",
  "max_steps": 32,
  "enable_recording": true
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the task.
- **status** (string) - The current status of the task (e.g., "waiting", "running", "done", "failed", "cancelled").
- **output** (any) - The output of the task once completed. Can be null.
- **credits_used** (integer) - The number of credits used for this task. Can be null.

#### Response Example
```json
{
  "id": "task_abc123",
  "status": "done",
  "output": {
    "stories": [
      {
        "title": "Example Story 1",
        "url": "http://example.com/story1"
      }
    ]
  },
  "credits_used": 1
}
```
```

--------------------------------

### Task Response API

Source: https://docs.smooth.sh/api-reference/agent/run-task

Details the response model for a submitted task, including credits used, balance, device information, and URLs for live interaction and recordings. It also outlines possible statuses and common error responses.

```APIDOC
## POST /websites/smooth_sh

### Description
Submits a task and returns a response model detailing the task's status, resource usage, and access URLs.

### Method
POST

### Endpoint
/websites/smooth_sh

### Parameters
#### Query Parameters
None

#### Request Body
None specified in the provided documentation, but implied by the task submission nature.

### Request Example
```json
{
  "example": "No specific request body example provided, but typically includes task parameters."
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the task.
- **status** (string) - The current status of the task (e.g., 'waiting').
- **output** (any) - The output of the task, if available.
- **credits_used** (integer) - The amount of credits consumed by the task.
- **credits_balance** (integer) - The remaining credits on the account.
- **device** (string) - The type of device used ('desktop' or 'mobile').
- **live_url** (string) - URL to interact with the live task execution.
- **recording_url** (string) - URL to view the task recording.

#### Response Example
```json
{
  "example": {
    "id": "<string>",
    "status": "waiting",
    "output": null,
    "credits_used": 123,
    "credits_balance": 123,
    "device": "desktop",
    "live_url": "<string>",
    "recording_url": "<string>"
  }
}
```

#### Error Responses
- **400 Bad Request**: Indicates an invalid request was made.
- **403 Forbidden**: Access to a premium feature was requested but is not available on the current plan.
- **422 Unprocessable Entity**: Indicates a validation error.
- **429 Too Many Requests**: Indicates that API credits have been exhausted.
```

--------------------------------

### Configure Proxy in Smooth Task (Python)

Source: https://docs.smooth.sh/features/proxies

This snippet shows how to configure and use a proxy server when running a task with the Smooth Python client. It requires the Smooth client library and specifies proxy server URL, username, and password as parameters. The output includes the live URL and the agent's response.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run(
  task="<my-task>",
  proxy_server="<my-proxy-url>",
  proxy_username="<my-proxy-username>",
  proxy_password="<my-proxy-password>",
)

print(f"Live URL: {task(.live_url())}")
print(f"Agent response: {task.result()}")
```

--------------------------------

### Write Task Instructions for Form Filling (Python)

Source: https://docs.smooth.sh/guides/fill-in-multi-step-dynamic-forms

This snippet demonstrates how to structure task instructions for filling out a multi-step form. It emphasizes providing a clear goal, necessary information, and expected output. The Python code defines a multi-line string for these instructions.

```python
task_instructions = """
Go to octopus.energy and get a quote for gas + electricity. Use the following information:

- 1, Garlic Row, Cambridge CB5 8HW
- Medium consumption

Return the final monthly estimate for all available tariffs.
"""

```

--------------------------------

### Delete Browser Profile using Python

Source: https://docs.smooth.sh/api-reference/profile/delete-profile

This snippet shows how to delete a browser profile using the Smooth.sh Python client. It supports both synchronous and asynchronous operations. You need to install the 'smooth' library and provide your API key and the profile ID.

```python
from smooth import SmoothClient

client = SmoothClient(api_key="YOUR_API_KEY")
client.delete_profile("my-profile")
print("Profile 'my-profile' deleted.")
```

```python
import asyncio
from smooth import SmoothAsyncClient

async def delete_profile():
    client = SmoothAsyncClient(api_key="YOUR_API_KEY")
    await client.delete_profile("my-profile")
    print("Profile 'my-profile' deleted.")
    await client.close()

asyncio.run(delete_profile())
```

--------------------------------

### Run Multi-Step Form Task with Smooth (Python)

Source: https://docs.smooth.sh/guides/fill-in-multi-step-dynamic-forms

This code snippet shows how to execute a task using the Smooth client, specifically for multi-step forms. It highlights setting a higher `max_steps` value to accommodate complex forms, printing the live URL, and retrieving the final task result.

```python
task = smooth_client.run(
    task=task_instructions,
    max_steps=64,  # Multi-step forms may require many steps
)

print(f"Live URL: {task.live_url()}")

# Get the result
result = task.result()
print(f"Insurance quote result: {result}")

```

--------------------------------

### List Browser Profiles with Python

Source: https://docs.smooth.sh/api-reference/profile/list-profiles

This snippet shows how to list browser profiles using the Smooth.sh Python client library. It supports both synchronous and asynchronous operations and requires an API key.

```python
from smooth import SmoothClient

client = SmoothClient(api_key="YOUR_API_KEY")
profiles = client.list_profiles()
print(profiles.profile_ids)
```

```python
import asyncio
from smooth import SmoothAsyncClient

async def list_profiles():
    client = SmoothAsyncClient(api_key="YOUR_API_KEY")
    profiles = await client.list_profiles()
    print(profiles.profile_ids)
    await client.close()

asyncio.run(list_profiles())
```

--------------------------------

### Upload File using SmoothClient

Source: https://docs.smooth.sh/guides/file-uploads

Demonstrates how to upload a file using the `SmoothClient.upload_file()` method. This method takes a file object and a name for the file. It's recommended to use descriptive names, especially when uploading multiple files. An optional `purpose` can also be provided.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")

file = smooth_client.upload_file(
  file=open("/path/to/file.png", "rb"),
  name="meaningful_file_name.png"
)
```

--------------------------------

### List Browser Profiles with JavaScript

Source: https://docs.smooth.sh/api-reference/profile/list-profiles

This snippet demonstrates how to list browser profiles using JavaScript with the Fetch API. It requires an API key for authentication and handles potential HTTP errors.

```javascript
const apiKey = 'YOUR_API_KEY';
const url = 'https://api.smooth.sh/api/v1/browser/profile';

async function listProfiles() {
  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'apikey': apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Available profiles:', data.r.profile_ids);
  } catch (error) {
    console.error('Error listing profiles:', error);
  }
}

listProfiles();
```

--------------------------------

### Run Task via JavaScript

Source: https://docs.smooth.sh/api-reference/agent/run-task

This JavaScript code utilizes the `fetch` API to submit a task to the Smooth.sh API. It defines the task payload, including the task description, device, and other parameters. The code handles the POST request and logs the response or any errors encountered.

```javascript
const apiKey = 'YOUR_API_KEY';
const url = 'https://api.smooth.sh/api/v1/task';

const payload = {
  task: 'Go to hacker news and get the top 5 stories.',
  device: 'desktop',
  max_steps: 32,
  enable_recording: true
};

async function runTask() {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'apikey': apiKey
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Task submitted:', data);
    // You can now use data.r.id to poll the get task endpoint
  } catch (error) {
    console.error('Error running task:', error);
  }
}

runTask();
```

--------------------------------

### Run Task via cURL

Source: https://docs.smooth.sh/api-reference/agent/run-task

This snippet demonstrates how to submit a task to the Smooth.sh API using cURL. It requires your API key and specifies the task details, device type, and maximum steps. The output is a JSON object containing the task ID and status.

```curl
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "Content-Type: application/json" \
     -H "apikey: YOUR_API_KEY" \
     -d '{
                 "task": "Go to hacker news and get the top 5 stories.",
                 "device": "desktop",
                 "max_steps": 32,
                 "enable_recording": true
               }'
```

--------------------------------

### Execute LinkedIn Enrichment Task (Python)

Source: https://docs.smooth.sh/guides/real-time-people-enrichment

Executes a pre-defined LinkedIn enrichment task using the Smooth client in Python. It initializes the client with an API key, runs the task, and prints the live URL, task results, and video recording URL.

```python
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")

task = smooth_client.run(
    task=linkedin_enrichment_task,
    enable_recording=True
)

print(f"Live URL: {task.live_url()}")
task_result = task.result()
print(f"Agent Response: {task_result.output}")
print(f"Task Video: {task_result.recording_url}")
```

--------------------------------

### Open Browser Session with Smooth.sh API (Python)

Source: https://docs.smooth.sh/api-reference/session/open-session

These Python snippets show how to open a browser session using the Smooth.sh API with both synchronous and asynchronous clients. They require an API key and allow specifying a session ID or creating a new random one. The code prints the live URL of the opened session and includes cleanup for the asynchronous client.

```python
from smooth import SmoothClient

client = SmoothClient(api_key="YOUR_API_KEY")
# If session_id is omitted, a random one is created
browser_session = client.open_session(session_id="my-session")
print(browser_session.live_url)
```

```python
import asyncio
from smooth import SmoothAsyncClient

async def open_session():
    client = SmoothAsyncClient(api_key="YOUR_API_KEY")
    # If session_id is omitted, a random one is created
    browser_session = await client.open_session(session_id="my-session")
    print(browser_session.live_url)
    await client.close()

asyncio.run(open_session())
```

--------------------------------

### Upload File using cURL

Source: https://docs.smooth.sh/api-reference/files/upload-file

This snippet demonstrates how to upload a file using a cURL command. It requires your API key and the path to the file you wish to upload.

```curl
curl -X POST "https://api.smooth.sh/api/v1/file" \
     -H "apikey: YOUR_API_KEY" \
     -F "file=@/path/to/your/file.txt"
```

--------------------------------

### Open Browser Session with Smooth.sh API (JavaScript)

Source: https://docs.smooth.sh/api-reference/session/open-session

This JavaScript code snippet demonstrates how to open a browser session using the Smooth.sh API via the Fetch API. It requires an API key and constructs a POST request with a JSON payload. The function handles the response, logs session details, and the live URL, with error handling for network or API issues.

```javascript
const apiKey = 'YOUR_API_KEY';

const url = 'https://api.smooth.sh/api/v1/browser/session';


// To create a new session with a random ID, omit the payload or send
an empty object

const payload = {
  session_id: 'my-persistent-session' // or null to create a new one
};

async function openSession() {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'apikey': apiKey
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Session opened:', data);
    console.log('Live URL:', data.r.live_url);
  } catch (error) {
    console.error('Error opening session:', error);
  }
}


openSession();
```

--------------------------------

### Python: Generate Structured Output with Pydantic Model

Source: https://docs.smooth.sh/features/structured-output

Demonstrates how to use a Pydantic BaseModel to define a structured output for an agent's response. This requires the 'smooth-py' library and Pydantic. The agent's output will conform to the defined model, enabling deterministic processing.

```python
# pip install smooth-py
from smooth import SmoothClient
from pydantic import BaseModel, Field

class MyStructuredOutput(BaseModel):
  my_output_data: list[int] = Field(description="A list of random numbers.")

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run("Output five random numbers.", response_model=MyStructuredOutput)

print(f"Agent response: {task.result()}")
```
Tokens:
Raw