---
title: "Run a task"
method: POST
path: "/v1/run/tasks"
tags: ["Agents"]
---

# Run a task

`POST /v1/run/tasks`

Run a task

## Headers

- `x-api-key` string, nullable
- `x-user-agent` string, nullable

## Request body

- TaskRunRequestInput
  - `prompt` string, required — The goal or task description for Skyvern to accomplish
  - `url` string, nullable — The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL
  - `engine` 'skyvern-1.0' | 'skyvern-2.0' | 'skyvern-3.0' | 'openai-cua' | 'anthropic-cua' | 'ui-tars' | 'yutori-navigator'
  - `title` string, nullable — The title for the task
  - `proxy_location` union — Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud. Available geotargeting options: - RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy. - RESIDENTIAL_ES: Spain - RESIDENTIAL_IE: Ireland - RESIDENTIAL_GB: United Kingdom - RESIDENTIAL_IN: India - RESIDENTIAL_JP: Japan - RESIDENTIAL_FR: France - RESIDENTIAL_DE: Germany - RESIDENTIAL_NZ: New Zealand - RESIDENTIAL_PH: Philippines - RESIDENTIAL_KR: South Korea - RESIDENTIAL_SA: Saudi Arabia - RESIDENTIAL_ZA: South Africa - RESIDENTIAL_AR: Argentina - RESIDENTIAL_AU: Australia - RESIDENTIAL_BR: Brazil - RESIDENTIAL_TR: Turkey - RESIDENTIAL_CA: Canada - RESIDENTIAL_MX: Mexico - RESIDENTIAL_IT: Italy - RESIDENTIAL_NL: Netherlands - RESIDENTIAL_ISP: ISP proxy - US-CA: California (deprecated, routes through RESIDENTIAL_ISP) - US-NY: New York (deprecated, routes through RESIDENTIAL_ISP) - US-TX: Texas (deprecated, routes through RESIDENTIAL_ISP) - US-FL: Florida (deprecated, routes through RESIDENTIAL_ISP) - US-WA: Washington (deprecated, routes through RESIDENTIAL_ISP) - NONE: No proxy For self-hosted deployments, you can pass a custom proxy URL as a dict: {"url": "http://user:password@proxy.example.com:8080"}. This routes the browser through your own proxy server and takes precedence over any globally configured proxy pool. Can also be a GeoTarget object for granular city/state targeting: {"country": "US", "subdivision": "CA", "city": "San Francisco"}
    - 'RESIDENTIAL' | 'US-CA' | 'US-NY' | 'US-TX' | 'US-FL' | 'US-WA' | 'RESIDENTIAL_ES' | 'RESIDENTIAL_IE' | 'RESIDENTIAL_GB' | 'RESIDENTIAL_IN' | 'RESIDENTIAL_JP' | 'RESIDENTIAL_FR' | 'RESIDENTIAL_DE' | 'RESIDENTIAL_NZ' | 'RESIDENTIAL_ZA' | 'RESIDENTIAL_AR' | 'RESIDENTIAL_AU' | 'RESIDENTIAL_BR' | 'RESIDENTIAL_TR' | 'RESIDENTIAL_CA' | 'RESIDENTIAL_MX' | 'RESIDENTIAL_IT' | 'RESIDENTIAL_NL' | 'RESIDENTIAL_PH' | 'RESIDENTIAL_KR' | 'RESIDENTIAL_SA' | 'RESIDENTIAL_ISP' | 'NONE'
    - GeoTarget — Granular proxy geo-targeting request with country, optional subdivision, and optional city.
      - `country` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
      - `subdivision` string, nullable — ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
      - `city` string, nullable — City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
    - object
  - `data_extraction_schema` union — The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/.
    - object
    - unknown[]
      - unknown
    - string
  - `error_code_mapping` object, nullable — Custom mapping of error codes to error messages if Skyvern encounters an error.
  - `max_steps` integer, nullable — Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact sales@skyvern.com for custom pricing.
  - `webhook_url` string, nullable — After a run is finished, send an update to this URL. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for more details.
  - `totp_identifier` string, nullable — Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details.
  - `totp_url` string, nullable — URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint for more details.
  - `browser_session_id` string, nullable — Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off.
  - `browser_profile_id` string, nullable — ID of a browser profile to reuse for this task
  - `start_fresh_browser` boolean — When true, start this run from a fresh, empty browser and ignore any saved browser memory — no memory is read or written. A verified sign-in during the run still updates the credential's saved login.
  - `model` object, nullable — Optional model configuration.
  - `extra_http_headers` object, nullable — The extra HTTP headers for the requests in browser.
  - `cdp_connect_headers` object, nullable — HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Use this for browser-provider auth (e.g., x-api-key for Skyvern Cloud, Browserless, or similar). These headers are NEVER forwarded to target websites.
  - `publish_workflow` boolean — Deprecated. Whether to publish a `skyvern-2.0` task as a reusable workflow. For backwards compatibility, this routes the request through the legacy `skyvern-2.0` publish path. Prefer creating reusable workflows through the workflow APIs.
  - `include_action_history_in_verification` boolean, nullable — Whether to include action history when verifying that the task is complete
  - `max_screenshot_scrolls` integer, nullable — The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.
  - `browser_address` string, nullable — The CDP address for the task.
  - `run_with` string, nullable — Whether to run the task with agent or code. Null means use the default.
  - `file_ids` string[], nullable — Ids of files uploaded through `POST /v1/upload_file` to attach to this run. Skyvern deletes an attached file as soon as the run finishes, so there is nothing to clean up afterwards. Reference an attached file by its id anywhere a file URL is accepted (for example in `parameters` or in the prompt) and no presigned URL is ever created for it. A file can be attached to one run at a time, and must not already be deleted.

## Response `200`

Successfully run task

- TaskRunResponse
  - `run_id` string, required — Unique identifier for this run. Run ID starts with `tsk_` for task runs and `wr_` for workflow runs.
  - `status` 'created' | 'queued' | 'running' | 'paused' | 'timed_out' | 'failed' | 'terminated' | 'completed' | 'canceled', required
  - `output` union — Output data from the run, if any. Format/schema depends on the data extracted by the run.
    - object
    - unknown[]
      - unknown
    - string
  - `downloaded_files` FileInfo[], nullable — List of files downloaded during the run
    - `url` string, required — URL to access the file
    - `checksum` string, nullable — SHA-256 checksum of the file
    - `filename` string, nullable — Original filename
    - `file_size` integer, nullable — Size of the file in bytes
    - `modified_at` string, date-time, nullable — Modified time of the file
    - `artifact_id` string, nullable — Artifact row id for refresh-on-read
  - `recording_url` string, nullable — URL to the recording of the run
  - `recording_archived` boolean — True when the recording exists but has been archived to cold storage and is not currently accessible.
  - `screenshot_urls` string[], nullable — List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot.
  - `failure_reason` string, nullable — Reason for failure if the run failed or terminated
  - `created_at` string, date-time, required — Timestamp when this run was created
  - `modified_at` string, date-time, required — Timestamp when this run was last modified
  - `queued_at` string, date-time, nullable — Timestamp when this run was queued
  - `started_at` string, date-time, nullable — Timestamp when this run started execution
  - `finished_at` string, date-time, nullable — Timestamp when this run finished
  - `app_url` string, nullable — URL to the application UI where the run can be viewed
  - `browser_session_id` string, nullable — ID of the Skyvern persistent browser session used for this run
  - `browser_profile_id` string, nullable — ID of the browser profile used for this run
  - `max_screenshot_scrolls` integer, nullable — The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot
  - `script_run` ScriptRunResponse
    - `ai_fallback_triggered` boolean
    - `script_id` string, nullable
    - `script_revision_id` string, nullable
  - `errors` object[], nullable — The errors for the run
  - `step_count` integer, nullable — Total number of steps executed in this run
  - `run_type` 'task_v1' | 'task_v2' | 'task_v3' | 'openai_cua' | 'anthropic_cua' | 'ui_tars' | 'yutori_navigator', required — Types of a task run - task_v1, task_v2, openai_cua, anthropic_cua, ui_tars
  - `run_request` TaskRunRequestOutput
    - `prompt` string, required — The goal or task description for Skyvern to accomplish
    - `url` string, nullable — The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL
    - `engine` 'skyvern-1.0' | 'skyvern-2.0' | 'skyvern-3.0' | 'openai-cua' | 'anthropic-cua' | 'ui-tars' | 'yutori-navigator'
    - `title` string, nullable — The title for the task
    - `proxy_location` union — Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud. Available geotargeting options: - RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy. - RESIDENTIAL_ES: Spain - RESIDENTIAL_IE: Ireland - RESIDENTIAL_GB: United Kingdom - RESIDENTIAL_IN: India - RESIDENTIAL_JP: Japan - RESIDENTIAL_FR: France - RESIDENTIAL_DE: Germany - RESIDENTIAL_NZ: New Zealand - RESIDENTIAL_PH: Philippines - RESIDENTIAL_KR: South Korea - RESIDENTIAL_SA: Saudi Arabia - RESIDENTIAL_ZA: South Africa - RESIDENTIAL_AR: Argentina - RESIDENTIAL_AU: Australia - RESIDENTIAL_BR: Brazil - RESIDENTIAL_TR: Turkey - RESIDENTIAL_CA: Canada - RESIDENTIAL_MX: Mexico - RESIDENTIAL_IT: Italy - RESIDENTIAL_NL: Netherlands - RESIDENTIAL_ISP: ISP proxy - US-CA: California (deprecated, routes through RESIDENTIAL_ISP) - US-NY: New York (deprecated, routes through RESIDENTIAL_ISP) - US-TX: Texas (deprecated, routes through RESIDENTIAL_ISP) - US-FL: Florida (deprecated, routes through RESIDENTIAL_ISP) - US-WA: Washington (deprecated, routes through RESIDENTIAL_ISP) - NONE: No proxy For self-hosted deployments, you can pass a custom proxy URL as a dict: {"url": "http://user:password@proxy.example.com:8080"}. This routes the browser through your own proxy server and takes precedence over any globally configured proxy pool. Can also be a GeoTarget object for granular city/state targeting: {"country": "US", "subdivision": "CA", "city": "San Francisco"}
      - 'RESIDENTIAL' | 'US-CA' | 'US-NY' | 'US-TX' | 'US-FL' | 'US-WA' | 'RESIDENTIAL_ES' | 'RESIDENTIAL_IE' | 'RESIDENTIAL_GB' | 'RESIDENTIAL_IN' | 'RESIDENTIAL_JP' | 'RESIDENTIAL_FR' | 'RESIDENTIAL_DE' | 'RESIDENTIAL_NZ' | 'RESIDENTIAL_ZA' | 'RESIDENTIAL_AR' | 'RESIDENTIAL_AU' | 'RESIDENTIAL_BR' | 'RESIDENTIAL_TR' | 'RESIDENTIAL_CA' | 'RESIDENTIAL_MX' | 'RESIDENTIAL_IT' | 'RESIDENTIAL_NL' | 'RESIDENTIAL_PH' | 'RESIDENTIAL_KR' | 'RESIDENTIAL_SA' | 'RESIDENTIAL_ISP' | 'NONE'
      - GeoTarget — Granular proxy geo-targeting request with country, optional subdivision, and optional city.
        - `country` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
        - `subdivision` string, nullable — ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
        - `city` string, nullable — City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
      - object
    - `data_extraction_schema` union — The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/.
      - object
      - unknown[]
        - unknown
      - string
    - `error_code_mapping` object, nullable — Custom mapping of error codes to error messages if Skyvern encounters an error.
    - `max_steps` integer, nullable — Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact sales@skyvern.com for custom pricing.
    - `webhook_url` string, nullable — After a run is finished, send an update to this URL. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for more details.
    - `totp_identifier` string, nullable — Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details.
    - `totp_url` string, nullable — URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint for more details.
    - `browser_session_id` string, nullable — Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off.
    - `browser_profile_id` string, nullable — ID of a browser profile to reuse for this task
    - `start_fresh_browser` boolean — When true, start this run from a fresh, empty browser and ignore any saved browser memory — no memory is read or written. A verified sign-in during the run still updates the credential's saved login.
    - `model` object, nullable — Optional model configuration.
    - `extra_http_headers` object, nullable — The extra HTTP headers for the requests in browser.
    - `cdp_connect_headers` object, nullable — HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Use this for browser-provider auth (e.g., x-api-key for Skyvern Cloud, Browserless, or similar). These headers are NEVER forwarded to target websites.
    - `publish_workflow` boolean — Deprecated. Whether to publish a `skyvern-2.0` task as a reusable workflow. For backwards compatibility, this routes the request through the legacy `skyvern-2.0` publish path. Prefer creating reusable workflows through the workflow APIs.
    - `include_action_history_in_verification` boolean, nullable — Whether to include action history when verifying that the task is complete
    - `max_screenshot_scrolls` integer, nullable — The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.
    - `browser_address` string, nullable — The CDP address for the task.
    - `run_with` string, nullable — Whether to run the task with agent or code. Null means use the default.
    - `file_ids` string[], nullable — Ids of files uploaded through `POST /v1/upload_file` to attach to this run. Skyvern deletes an attached file as soon as the run finishes, so there is nothing to clean up afterwards. Reference an attached file by its id anywhere a file URL is accepted (for example in `parameters` or in the prompt) and no presigned URL is ever created for it. A file can be attached to one run at a time, and must not already be deleted.

## Other responses

- `400` — Invalid agent engine
- `422` — Validation Error

---

[API](https://skmtc.net/skyvern-ai/apis/skyvern-api-2.md) · [All operations](https://skmtc.net/skyvern-ai/apis/skyvern-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/skyvern-ai/skyvern-api-2/revisions/89037b86e004/schema)