Run a task

Authentication

x-api-keystring

API Key authentication via header

Request

This endpoint expects an object.

promptstringRequired

The goal or task description for Skyvern to accomplish

urlstringOptional

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

engineenumOptional

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.

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.

Allowed values:

titlestringOptional

The title for the task

proxy_locationenumOptional

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_ZA: South Africa
RESIDENTIAL_AR: Argentina
RESIDENTIAL_AU: Australia
RESIDENTIAL_ISP: ISP proxy
US-CA: California
US-NY: New York
US-TX: Texas
US-FL: Florida
US-WA: Washington
NONE: No proxy

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_ZA: South Africa - RESIDENTIAL_AR: Argentina - RESIDENTIAL_AU: Australia - RESIDENTIAL_ISP: ISP proxy - US-CA: California - US-NY: New York - US-TX: Texas - US-FL: Florida - US-WA: Washington - NONE: No proxy

data_extraction_schemamap from strings to any or list of any or stringOptional

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

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_mappingmap from strings to stringsOptional

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

max_stepsintegerOptional

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_urlstringOptional

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_identifierstringOptional

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_urlstringOptional

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_idstringOptional

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.

modelmap from strings to anyOptional

Optional model configuration.

extra_http_headersmap from strings to stringsOptional

The extra HTTP headers for the requests in browser.

publish_workflowbooleanOptionalDefaults to false

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

include_action_history_in_verificationbooleanOptionalDefaults to false

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

max_screenshot_scrollsintegerOptional

The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.

browser_addressstringOptional

The CDP address for the task.

Response

Successfully run task

run_idstring

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

statusenum

Current status of the run

created_atstringformat: "date-time"

Timestamp when this run was created

modified_atstringformat: "date-time"

Timestamp when this run was last modified

run_typeenum

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

Allowed values:

outputmap from strings to any or list of any or string or null

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

downloaded_fileslist of objects or null

List of files downloaded during the run

recording_urlstring or null

URL to the recording of the run

screenshot_urlslist of strings or null

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

failure_reasonstring or null

Reason for failure if the run failed or terminated

queued_atstring or nullformat: "date-time"

Timestamp when this run was queued

started_atstring or nullformat: "date-time"

Timestamp when this run started execution

finished_atstring or nullformat: "date-time"

Timestamp when this run finished

app_urlstring or null

URL to the application UI where the run can be viewed

browser_session_idstring or null

ID of the Skyvern persistent browser session used for this run

max_screenshot_scrollsinteger or null

The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot

script_runobject or null

The script run result

errorslist of maps from strings to any or null

The errors for the run

run_requestobject or null

The original request parameters used to start this task run

1	{
2	"run_id": "tsk_123",
3	"status": "created",
4	"created_at": "2025-01-01T00:00:00Z",
5	"modified_at": "2025-01-01T00:05:00Z",
6	"run_type": "task_v1",
7	"output": {},
8	"downloaded_files": [
9	{
10	"url": "foo",
11	"checksum": "foo",
12	"filename": "foo",
13	"modified_at": "foo"
14	}
15	],
16	"recording_url": "foo",
17	"screenshot_urls": [
18	"foo"
19	],
20	"failure_reason": "foo",
21	"queued_at": "foo",
22	"started_at": "foo",
23	"finished_at": "foo",
24	"app_url": "foo",
25	"browser_session_id": "foo",
26	"max_screenshot_scrolls": 42,
27	"script_run": {
28	"ai_fallback_triggered": false
29	},
30	"errors": [
31	{}
32	],
33	"run_request": {
34	"prompt": "Find the top 3 posts on Hacker News.",
35	"url": "foo",
36	"engine": "skyvern-1.0",
37	"title": "foo",
38	"proxy_location": "RESIDENTIAL",
39	"data_extraction_schema": {},
40	"error_code_mapping": {},
41	"max_steps": 42,
42	"webhook_url": "foo",
43	"totp_identifier": "foo",
44	"totp_url": "foo",
45	"browser_session_id": "foo",
46	"model": {},
47	"extra_http_headers": {},
48	"publish_workflow": false,
49	"include_action_history_in_verification": true,
50	"max_screenshot_scrolls": 42,
51	"browser_address": "foo"
52	}
53	}

Run a task

Authentication

Headers

Request

Response

Errors

1	from skyvern import Skyvern
2
3	skyvern = Skyvern(api_key="YOUR_API_KEY")
4	await skyvern.run_task(prompt="What's the top post on hackernews?")