Tasks

Tasks API

The core building block in Skyvern

Tasks are the building block of Skyvern. They represent a single instruction (goal) to the browser to go do something using language models. Ex. “Go to alibaba and extract this information”

Request - Initiate a task

Request type: POST

Production: https://api.skyvern.com/v1/run/tasks

ParameterTypeRequired?Sample ValueDescription
x-api-keyStringyes[your-api-key-here]Bearer token that gives your backend access to the Skyvern API. This will be manually provided by us

Body

ParameterTypeRequired?Sample ValueDescription
promptStringyes”Apply for a job”The goal or task description for Skyvern to accomplish
urlStringnohttps://www.example.comThe starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL
titleStringno”Job Application Task”Optional title for the task
engineStringno”skyvern-2.0”The Skyvern engine version to use for this task. Supported values are “skyvern-1.0” and “skyvern-2.0”. Default is “skyvern-2.0”
proxy_locationStringno”RESIDENTIAL”Geographic Proxy location to route the browser traffic through. Default is “RESIDENTIAL”
data_extraction_schemaObjectno{ “success”: { “type”: “boolean” } }Schema defining what data should be extracted from the webpage
error_code_mappingObjectno{ “AUTH_FAILED”: “Authentication failed” }Custom mapping of error codes to error messages if Skyvern encounters an error
max_stepsIntegerno10Maximum number of steps the task can take before timing out
webhook_urlStringnohttps://api.example.com/webhookURL to send task status updates to after a run is finished
totp_identifierStringno”user@example.com”Identifier for TOTP (Time-based One-Time Password) authentication if codes are being pushed to Skyvern
totp_urlStringnohttps://api.example.com/totpURL for TOTP authentication setup if Skyvern should be polling endpoint for 2FA codes
browser_session_idStringno”sess_123”ID of an existing browser session to reuse, having it continue from the current screen state
publish_workflowBooleannofalseWhether to publish this task as a reusable workflow. Default is false

Example Request (Apply for a job)

1POST https://api.skyvern.com/v1/run/tasks
2
3{
4    "prompt": "Apply for a job on behalf of this person: name: Chris P Bacon. email: chris@pbacon.com",
5    "url": "https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply",
6    "title": "Job Application Task",
7    "engine": "skyvern-2.0",
8    "proxy_location": "RESIDENTIAL",
9    "data_extraction_schema": {
10        "application_success": {
11            "type": "boolean"
12        }
13    }
14}

Response

Each task run has an associated run_id — a unique identifier you can use to look up information about any task run.

ParameterTypeAlways returned?Sample ValueDescription
run_idStringyes”t_123456” or “oc_12345”Unique identifier for this run
statusStringyes”running”Current status of the run. Possible values: “created”, “queued”, “running”, “timed_out”, “failed”, “terminated”, “completed”, “canceled”
outputObject/Array/String/nullno{ “success”: true }Output data from the run, if any. Format depends on the schema in the input
downloaded_filesArray/nullno[{ “url”: ”…”, “checksum”: ”…”, “filename”: ”…” }]List of files downloaded during the run
recording_urlStringno”https://…”URL to the recording of the run
failure_reasonStringno”Max steps exceeded”Reason for failure if the run failed
created_atStringyes”2024-03-20T10:00:00Z”Timestamp when this run was created
modified_atStringyes”2024-03-20T10:05:00Z”Timestamp when this run was last modified
run_typeStringyes”task_v2”Type of task run - either task_v1 or task_v2
run_requestObjectyes{…}The original request parameters used to start this task run

Request - Task Details (GET)

You can use this API to poll for task status updates if you don’t want to wait for webhook callbacks.

Request type: GET

Production: https://api.skyvern.com/v1/run/tasks/{run_id}

ParameterTypeRequired?Sample ValueDescription
run_idStringyes”run_123”The id of the run you want to check the status of

Request - List Task Run Details (GET)

Request type: GET

Production:api.skyvern.com/api/v1/tasks/

ParameterTypeRequired?Sample ValueDescription
pageIntegerno1default=1, has to be ≥1
page_sizeIntegerno10default=10, has to be ≥1

Response - Task Details (GET)

Production: https://api.skyvern.com/v1/runs/{run_id}

The response follows the same schema as the task creation response, containing:

ParameterTypeSample ValueDescription
run_idString”t_123456”Unique identifier for this run
statusString”created”Current status of the run. Possible values: “created”, “queued”, “running”, “timed_out”, “failed”, “terminated”, “completed”, “canceled”
outputObject{ “additionalProp1”: { } }Output data from the run
downloaded_filesArray[{ “url”: “string”, “checksum”: “string”, “filename”: “string” }]List of files downloaded during the run
recording_urlString”https://…”URL to the recording of the run
failure_reasonString”Max steps exceeded”Reason for failure if the run failed
created_atString”2025-04-03T14:08:29.505Z”Timestamp when this run was created
modified_atString”2025-04-03T14:08:29.505Z”Timestamp when this run was last modified
run_typeString”task_v1”Type of task run - either task_v1 or task_v2
run_requestObject{ “prompt”: “string”, “url”: “string”, “title”: “string”, “engine”: “skyvern-2.0”, “proxy_location”: “RESIDENTIAL”, “data_extraction_schema”: { “additionalProp1”: { } }, “error_code_mapping”: { “additionalProp1”: “string” }, “max_steps”: 0, “webhook_url”: “string”, “totp_identifier”: “string”, “totp_url”: “string”, “browser_session_id”: “string”, “publish_workflow”: false }The original request parameters used to start this task run

Request - List Steps (GET)

Each task run is made up of “steps” which are the individual actions Skyvern takes to complete the task. You can use this endpoint to get all the steps of the run.

Request type: GET

Production: https://api.skyvern.com/api/v1/tasks/{task_id}/steps

Response - List Steps (GET)

The response is a list of Step Objects.

Step Object

ParameterTypeSample ValueDescription
organization_idStringo_123Your organization id
task_idStringtsk_123The id of the task
step_idStringstp_123The id of the step
statusStringcreated / running / completed / failed / canceledThe status of the step
orderInteger0 / 1 / 2The zero based index of the step. 0 is the first step of the task.
retry_indexInteger0 / 1 / 2 / 3When a step fails, the retry step will have a retry_index that’s larger than 0
input_token_countInteger19223The number of input tokens used in this step
output_token_countInteger500The number of output tokens generated in this step

Request - Cancel A Task (POST)

A task that’s in any of these states can be canceled: [“created”, “queued”, “running”]. This stops the execution of the task.

Request type: POST

Production: https://api.skyvern.com/v1/runs/{run_id}/cancel