---
title: "Submit task"
method: POST
path: "/api/v1/task"
---

# Submit task

`POST /api/v1/task`

Submit a task.

## Cookies

- `apikey` string

## Request body

- TaskRequest — Run task request model.
  - `task` string, nullable — The task to run. If None, opens a blank browser and waits for further instructions.
  - `response_model` object, nullable — If provided, the JSON schema describing the desired output structure. Default is None
  - `url` string, nullable — The starting URL for the task. If not provided, the agent will infer it from the task.
  - `metadata` object, nullable — A dictionary containing variables or parameters that will be passed to the agent.
  - `files` string[], nullable — A list of file ids to pass to the agent.
  - `agent` string — The agent to use for the task. Default is 'smooth'.
  - `max_steps` integer — Maximum number of steps the agent can take (min 2, max 128).
  - `device` 'desktop' | 'mobile' | 'desktop-lg' — Device type for the task. Default is desktop.
  - `allowed_urls` string[], nullable — List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*). If None, all URLs are allowed.
  - `enable_recording` boolean — Enable video recording of the task execution. Default is True
  - `profile_id` string, nullable — Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials.
  - `profile_read_only` 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.
  - `stealth_mode` boolean — (Deprecated, ignored) Use `use_stealth` instead. Stealth is on by default.
  - `use_stealth` boolean — Run the browser in stealth mode. Default is True.
  - `proxy_server` string, nullable — Proxy server url to route browser traffic through.
  - `proxy_username` string, nullable — Proxy server username.
  - `proxy_password` string, password, nullable — Proxy server password.
  - `proxy_id` string, nullable — Name of a Smooth-managed proxy to route browser traffic through, as returned by `list_proxies()`. Cannot be combined with `proxy_server`.
  - `certificates` Certificate[], nullable — 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('cert.p12', 'rb')). - `password` (optional): Password to decrypt the certificate file.
    - `file` union, required — p12 file object to be uploaded (e.g., open('cert.p12', 'rb')).
      - string, password
      - unknown
    - `password` string, password, nullable — Password to decrypt the certificate file. Optional.
    - `filters` array[], nullable — Reserved for future use to specify URL patterns where the certificate should be applied. Optional.
      - string[]
  - `use_adblock` boolean, nullable — Enable adblock for the browser session. Default is True.
  - `use_captcha_solver` boolean, nullable — Enable captcha solver for the browser session. Default is True.
  - `additional_tools` object, nullable — Additional tools to enable for the task.
  - `custom_tools` ToolSignature[], nullable — Custom tools to register for the task.
    - `name` string, required — The name of the tool.
    - `description` string, required — A brief description of the tool.
    - `inputs` object, required — The input parameters for the tool.
    - `output` string, required — The output produced by the tool.
  - `experimental_features` object, nullable — Experimental features to enable for the task.
  - `extensions` string[], nullable — List of extensions to install for the task.
  - `show_cursor` boolean — Show mouse cursor. Default is False.
  - `cursor_text` string, nullable — Custom text shown in the cursor label bubble (max 16 characters). Requires show_cursor=True and a Growth plan.
  - `cursor_bubble_color` string, nullable — Custom hex color (e.g. '#0081ff') for the cursor label bubble. Requires show_cursor=True and a Growth plan.
  - `idle_timeout` integer, nullable — Seconds of inactivity (no task, goto, evaluate_js, or extract) after which an open session auto-closes. Only applies to sessions (task is None). None uses the server default (5 minutes); 0 or negative disables auto-close.

## Response `200`

Successful Response

- ApiResponseTaskResponse
  - `r` TaskResponse, required — Task response model.
    - `id` string, required — The ID of the task.
    - `status` 'waiting' | 'running' | 'done' | 'failed' | 'cancelled', required — The status of the task.
    - `output` unknown
    - `credits_used` integer, nullable — The amount of credits used to perform the task.
    - `device` 'desktop' | 'mobile' | 'desktop-lg', nullable — The device type used for the task.
    - `live_url` string, nullable — The URL to view and interact with the task execution.
    - `recording_url` string, nullable — The URL to view the task recording.
    - `downloads_url` string, nullable — The URL of the archive containing the downloaded files.
    - `network_har_url` string, nullable — Presigned URL of the network HAR (gzipped) capturing the task's network activity.
    - `console_log_url` string, nullable — Presigned URL of the timestamped browser console log.
    - `session_log` object[], nullable — Timestamped log of the session's steps and actions.
    - `created_at` integer, nullable — The timestamp when the task was created.
    - `tool_calls` object, nullable — Contains a list of pending tool calls.
    - `events` TaskEvent[], nullable — The list of new events fired.
      - `name` string, required — The name of the event.
      - `payload` object, required — The payload of the event.
      - `id` string, nullable — The ID of the event.
      - `timestamp` integer, nullable — The timestamp of the event.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/smooth/apis/circlemind-zero.md) · [All operations](https://skmtc.dev/smooth/apis/circlemind-zero/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smooth/circlemind-zero/revisions/472956a12adf/schema)