> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smooth.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Simple Task

> Run a one-shot browser automation task

<Note>
  For complex multi-step workflows or when you need more control, see [Session Workflows](/methods/session).
</Note>

## Setting up

Get your free API key and start running tasks in minutes.

<Card title="Get your free API key" icon="key" href="https://app.smooth.sh" horizontal>
  Unlock your free welcome credits. No credit card required.
</Card>

## Launch a task using the Python SDK

Launch your first task in 4 lines of code. Under the hood, `client.run()` creates a browser session, runs the task, and returns the result.

<CodeGroup>
  ```python Python theme={null}
  # 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()}")
  ```
</CodeGroup>

<Note>
  If Python is not your language of choice, check out our [API Reference](/api-reference/introduction).
</Note>

## Request

All parameters available when running a task.

<ResponseField name="task" type="string" required>
  The task for the agent to execute.

  Example: `Go to Google Flights and find the cheapest flight from London to Paris today`
</ResponseField>

<ResponseField name="response_model" type="dict | BaseModel">
  If provided, enforces a structured output schema.
  It can be a dictionary describing a JSON schema or a Pydantic Model.
  Default: `None`.

  Example:

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "output": {
        "type": "integer",
        "description": "The integer part of the result of the calculation"
      }
    }
  }
  ```
</ResponseField>

<ResponseField name="agent" type="string">
  The agent that will run the task. Currently, only `smooth` is available. Default: `smooth`.

  Example: `smooth`
</ResponseField>

<ResponseField name="max_steps" type="int">
  The upper limit on the number of steps the agent can take during task execution. The range is from 2 to 128. Default: 32.

  Example: `64`
</ResponseField>

<ResponseField name="device" type="string">
  The type of device for the task execution. Choose between `mobile` or `desktop`. Default: `mobile`.

  Example: `desktop`
</ResponseField>

<ResponseField name="enable_recording" type="boolean">
  Toggles the option to record a video of the task execution. Default: True.

  Example: `True`
</ResponseField>

### Advanced Parameters

<ResponseField name="url" type="string">
  The starting URL for the task. If not provided, the agent will infer it from the task.

  Example: `https://amazon.com`
</ResponseField>

<ResponseField name="allowed_urls" type="list">
  List of allowed URL patterns using wildcard syntax. If None, all URLs are allowed.

  Example: \["google.com/\*", "\*mydomain.\*/\*"]
</ResponseField>

<ResponseField name="metadata" type="dict">
  A dictionary containing variables or parameters that will be passed to the agent.

  Example: `{"username": "my_username"}`
</ResponseField>

<ResponseField name="files" type="list">
  A list of file ids to be passed to the agent.

  Check out our guide on [File uploads](/guides/file-uploads)
</ResponseField>

<ResponseField name="profile_id" type="string">
  The browser profile ID to be utilized. Each profile retains its own state, including login credentials and cookies. You must create the profile first using `client.create_profile()`. See [Browser Profiles](/methods/profiles).

  Example: `profile_12345`
</ResponseField>

<ResponseField name="profile_read_only" type="boolean">
  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. Default: False.
</ResponseField>

<ResponseField name="use_adblock" type="boolean">
  Enable adblock for the browser session. Default is True.
</ResponseField>

<ResponseField name="stealth_mode" type="boolean">
  Activates stealth mode for the browser, which helps in avoiding detection. Default: True.

  Example: `True`
</ResponseField>

<ResponseField name="proxy_server" type="string">
  The hostname or IP address of the proxy server that will be used for the session.

  Set to `"self"` to create a P2P tunnel through your machine, routing traffic via your IP and enabling access to localhost. See [P2P Tunnel](/features/use-my-ip) for details.

  Example: `proxy.example.com` or `self`
</ResponseField>

<ResponseField name="proxy_username" type="string">
  The username for authenticating with the proxy server, if authentication is required.

  Example: `user123`
</ResponseField>

<ResponseField name="proxy_password" type="string">
  The password for authenticating with the proxy server, if authentication is required.

  Example: `password123`
</ResponseField>

<ResponseField name="certificates" type="list">
  List of client certificates to use when accessing secure websites. Each certificate is a dictionary with the following fields:

  * `file`: p12 file object to be uploaded (e.g., open('my\_cert.p12', 'rb'));
  * `password` (optional): The password for the certificate file, if applicable.

  <CodeGroup>
    ```python Python theme={null}
    task = client.run(
     ...,
     certificates=[{
       "file": open("my_cert.p12", "rb"),
       "password": "my_password"
     }]
    )
    ```
  </CodeGroup>
</ResponseField>

<ResponseField name="additional_tools" type="dict">
  Additional tools to enable for the task. Each tool is a `{tool_name: tool_kwargs}` pair. Use `tool_kwargs = None` for the default configuration of any tool.

  See the [Tools](/methods/tools-overview) page for a complete list of available tools and their configuration options.

  <CodeGroup>
    ```python Python theme={null}
    task = client.run(
     ...,
     additional_tools={
       "screenshot": {"full_page": True},
       "hover": None
     }
    )
    ```
  </CodeGroup>
</ResponseField>

<ResponseField name="custom_tools" type="list">
  A list of custom Python functions that the agent can call during task execution. Custom tools run in your local environment and can be used for OTP handling, human-in-the-loop scenarios, database operations, API integrations, and more.

  See the [Custom Tools](/methods/custom-tools) page for detailed documentation and examples.
</ResponseField>

<ResponseField name="experimental_features" type="dict">
  Experimental features to enable for the task.
</ResponseField>

## Response

Returns a `TaskHandle` with the following attributes.

<ResponseField name="id()" type="method">
  Returns the ID of the task.
</ResponseField>

<ResponseField name="live_url()" type="method">
  Returns a live URL where you can see the agent in action.

  Set `interactive=True` to get an interactive view.

  Set `embed=True` to get an embeddable view (ideal for iframes).
</ResponseField>

<ResponseField name="result()" type="method">
  Waits for the task completion and returns a `TaskResponse` upon completion.
</ResponseField>

<ResponseField name="recording_url()" type="method">
  Waits for the task completion and returns a recording URL upon completion if `enable_recording` was enabled. You can use this link to download the video recording of the task. The video will be ready shortly after the task completes.
</ResponseField>

<ResponseField name="downloads_url()" type="method">
  Waits for the task completion and returns a URL of the archive containing the files downloaded during the execution. If no file was downloaded raises `ApiError`.
</ResponseField>

<ResponseField name="stop()" type="method">
  Cancel the task execution.
</ResponseField>

## Waiting for task completion

Use `result()` to wait for task completion.

<CodeGroup>
  ```python Python highlight={6} theme={null}
  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}")
  ```
</CodeGroup>

Returns a `TaskResponse` with the following attributes.

<ResponseField name="id" type="string">
  The ID of the task.
</ResponseField>

<ResponseField name="status" type="string">
  The status of the task. One of: \["waiting", "running", "done", "failed"]
</ResponseField>

<ResponseField name="output" type="any">
  The final response from the agent.
</ResponseField>

<ResponseField name="credits_used" type="int">
  The number of credits used. 1 credit corresponds to \$0.01.
</ResponseField>

<ResponseField name="device" type="string">
  The device type used for the task. One of: \["mobile", "desktop"]
</ResponseField>

<ResponseField name="created_at" type="number">
  The timestamp when the task was created.
</ResponseField>

## Cancelling a running task

Use `stop()` to cancel a running task.

<CodeGroup>
  ```python Python highlight={6} theme={null}
  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.stop()  # Cancel the task execution

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

  assert task_result.status == "cancelled"
  ```
</CodeGroup>