---
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 — Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.
- `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' | '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.
  - `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.

## 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' | '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' | '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.
    - `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.

## Other responses

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

---

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