Skip to main content
POST
/
v1
/
run
/
tasks
Run a task
curl --request POST \
  --url https://api.skyvern.com/v1/run/tasks \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Find the top 3 posts on Hacker News.",
  "url": "https://www.hackernews.com",
  "engine": "skyvern-2.0",
  "title": "The title of my first skyvern task",
  "proxy_location": "RESIDENTIAL",
  "data_extraction_schema": {},
  "error_code_mapping": {
    "login_failed": "The login credentials are incorrect or the account is locked"
  },
  "max_steps": 10,
  "webhook_url": "https://my-site.com/webhook",
  "totp_identifier": "john.doe@example.com",
  "totp_url": "https://my-totp-service.com/totp",
  "browser_session_id": "pbs_123",
  "model": {},
  "extra_http_headers": {},
  "publish_workflow": false,
  "include_action_history_in_verification": false,
  "max_screenshot_scrolls": 123,
  "browser_address": "http://127.0.0.1:9222",
  "run_with": "agent"
}
'
{
  "run_id": "tsk_123",
  "status": "created",
  "created_at": "2025-01-01T00:00:00Z",
  "modified_at": "2025-01-01T00:05:00Z",
  "run_type": "task_v1",
  "output": {},
  "downloaded_files": [
    {
      "url": "<string>",
      "checksum": "<string>",
      "filename": "<string>",
      "modified_at": "2023-11-07T05:31:56Z"
    }
  ],
  "recording_url": "<string>",
  "screenshot_urls": [
    "<string>"
  ],
  "failure_reason": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "app_url": "https://app.skyvern.com/tasks/tsk_123",
  "browser_session_id": "pbs_123",
  "browser_profile_id": "bp_123",
  "max_screenshot_scrolls": 123,
  "script_run": {
    "ai_fallback_triggered": false
  },
  "errors": [
    {}
  ],
  "step_count": 123,
  "run_request": {
    "prompt": "Find the top 3 posts on Hacker News.",
    "url": "https://www.hackernews.com",
    "engine": "skyvern-2.0",
    "title": "The title of my first skyvern task",
    "proxy_location": "RESIDENTIAL",
    "data_extraction_schema": {},
    "error_code_mapping": {
      "login_failed": "The login credentials are incorrect or the account is locked"
    },
    "max_steps": 10,
    "webhook_url": "https://my-site.com/webhook",
    "totp_identifier": "john.doe@example.com",
    "totp_url": "https://my-totp-service.com/totp",
    "browser_session_id": "pbs_123",
    "model": {},
    "extra_http_headers": {},
    "publish_workflow": false,
    "include_action_history_in_verification": false,
    "max_screenshot_scrolls": 123,
    "browser_address": "http://127.0.0.1:9222",
    "run_with": "agent"
  }
}

Headers

​
x-api-key
string | null

Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

​
x-user-agent
string | null

Body

application/json
​
prompt
string
required

The goal or task description for Skyvern to accomplish

Example:

"Find the top 3 posts on Hacker News."

​
url
string | null

The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL

Example:

"https://www.hackernews.com"

​
engine
enum<string>
default:skyvern-2.0

The engine that powers the agent task. The default value is skyvern-2.0, the latest Skyvern agent that performs pretty well with complex and multi-step tasks. skyvern-1.0 is good for simple tasks like filling a form, or searching for information on Google. The openai-cua engine uses OpenAI's CUA model. The anthropic-cua uses Anthropic's Claude Sonnet 3.7 model with the computer use tool.

Available options:
skyvern-1.0,
skyvern-2.0,
openai-cua,
anthropic-cua,
ui-tars
​
title
string | null

The title for the task

Example:

"The title of my first skyvern task"

​
proxy_location
default:RESIDENTIAL

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_ZA: South Africa
  • RESIDENTIAL_AR: Argentina
  • RESIDENTIAL_AU: Australia
  • 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 Can also be a GeoTarget object for granular city/state targeting: {"country": "US", "subdivision": "CA", "city": "San Francisco"}
Available options:
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_ISP,
NONE
​
data_extraction_schema

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/.

​
error_code_mapping
Error Code Mapping · object

Custom mapping of error codes to error messages if Skyvern encounters an error.

Example:
{
  "login_failed": "The login credentials are incorrect or the account is locked"
}
​
max_steps
integer | null

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.

Example:

10

​
webhook_url
string | null

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.

Example:

"https://my-site.com/webhook"

​
totp_identifier
string | null

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.

Example:

"john.doe@example.com"

​
totp_url
string | null

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.

Example:

"https://my-totp-service.com/totp"

​
browser_session_id
string | null

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.

Example:

"pbs_123"

​
model
Model · object

Optional model configuration.

​
extra_http_headers
Extra Http Headers · object

The extra HTTP headers for the requests in browser.

​
publish_workflow
boolean
default:false

Whether to publish this task as a reusable workflow. Only available for skyvern-2.0.

​
include_action_history_in_verification
boolean | null
default:false

Whether to include action history when verifying that the task is complete

​
max_screenshot_scrolls
integer | null

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 | null

The CDP address for the task.

Example:

"http://127.0.0.1:9222"

​
run_with
string | null

Whether to run the task with agent or code.

Example:

"agent"

Response

Successfully run task

​
run_id
string
required

Unique identifier for this run. Run ID starts with tsk_ for task runs and wr_ for workflow runs.

Example:

"tsk_123"

​
status
enum<string>
required

Current status of the run

Available options:
created,
queued,
running,
timed_out,
failed,
terminated,
completed,
canceled
Example:

"created"

​
created_at
string<date-time>
required

Timestamp when this run was created

Example:

"2025-01-01T00:00:00Z"

​
modified_at
string<date-time>
required

Timestamp when this run was last modified

Example:

"2025-01-01T00:05:00Z"

​
run_type
enum<string>
required

Types of a task run - task_v1, task_v2, openai_cua, anthropic_cua, ui_tars

Available options:
task_v1,
task_v2,
openai_cua,
anthropic_cua,
ui_tars
​
output

Output data from the run, if any. Format/schema depends on the data extracted by the run.

​
downloaded_files
FileInfo · object[] | null

List of files downloaded during the run

​
recording_url
string | null

URL to the recording of the run

​
screenshot_urls
string[] | null

List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot.

​
failure_reason
string | null

Reason for failure if the run failed or terminated

​
queued_at
string<date-time> | null

Timestamp when this run was queued

​
started_at
string<date-time> | null

Timestamp when this run started execution

​
finished_at
string<date-time> | null

Timestamp when this run finished

​
app_url
string | null

URL to the application UI where the run can be viewed

Example:

"https://app.skyvern.com/tasks/tsk_123"

​
browser_session_id
string | null

ID of the Skyvern persistent browser session used for this run

Example:

"pbs_123"

​
browser_profile_id
string | null

ID of the browser profile used for this run

Example:

"bp_123"

​
max_screenshot_scrolls
integer | null

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 · object

The script run result

​
errors
Errors · object[] | null

The errors for the run

​
step_count
integer | null

Total number of steps executed in this run

​
run_request
TaskRunRequest · object

The original request parameters used to start this task run