Tasks API | 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/api/v1/tasks/

Parameter	Type	Required?	Sample Value	Description
x-api-key	String	yes	[your-api-key-here]	Bearer token that gives your backend access to the Skyvern API. This will be manually provided by us
x-max-steps-override	Integer	no	10	Overrides any max step configuration for the initiated task

Body

Parameter	Type	Required?	Sample Value	Description
url	HttpUrl	yes	https://www.example.com	It must be a http or https URL
navigation_goal	String	no	Apply for a job	The prompt that tells the agent what the user-facing goal is. This is the guiding light for the LLM as it navigates a particular website / sitemap to achieve this specified goal
data_extraction_goal	String	no	Was the job application successful?	The prompt that instructs the agent to extract information once the agent has achieved its user_goal
navigation_payload	Object	no	”name”: “Chris P. Bacon”, “email”: “mailto:chris@pbacon.com”	JSON-formatted payload with any “facts” or information that would help the agent perform its job. In the case of navigating an insurance quote, this payload would include any user information to help fill out the insurance flow such as date of birth, or age they got their license, and so on This can include nested information, and the formatting isn’t validated
webhook_callback_url	HttpUrl	no	…	The callback URL once our system is finished processing this async task
proxy_location	String	yes	RESIDENTIAL	Proxy location for the web-browsing request. Please pass RESIDENTIAL as a value
extracted_information_schema	JSON	no		Used to enforce a JSON schema spec to be enforced in the data_extraction_goal. Similar to https://json-schema.org/ definition.
totp_verification_url	HttpUrl	no	https://mywebsite.com/two_factor_code	The url of your TOTP endpoint. If this field is provided, Skyvern will call the url to fetch the TOTP/2FA/MFA code when needed
totp_identifier	String	no	myemail@example.com / 4155558888	The email address or the phone number which receives the TOTP/2FA/MFA code. If this field is provided, Skyvern will fetch the code that is pushed to Skyvern’s TOTP API

Example Request (Apply for a job)

1 POST https://api.skyvern.com/api/v1/tasks/ 
2 
3 {
4     "url": "https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply",
5     "navigation_goal": "Apply for a job",
6     "data_extraction_goal": "Was the job application successful?",
7     "proxy_location": "RESIDENTIAL",
8     "navigation_payload": {
9         "name": "Chris P. Bacon",
10         "email": "chris@pbacon.com"
11     }
12 }

Response

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

Parameter	Type	Always returned?	Sample Value	Description
task_id	String	yes	t_123456	The task id associated with this specific task

Response Webhook - Task conclusion (POST)

If a webhook_callback_url is specified within your task request, Skyvern will make a callback to your system letting you know that it has either finished, terminated or failed a task execution.

The following headers can be used to validate it’s an authentic Skyvern request.

Headers

Parameter	Type	Required?	Sample Value	Description
x-skyvern-signature	String	yes	v0=a2114d57b48eac39b9ad189 dd8316235a7b4a8d21a10bd275 19666489c69b503	Authentication token that allows our service to communicate with your backend service via callback / webhook We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request
x-skyvern-timestamp	String	yes	1531420618	Timestamp used to decode and validate the incoming webhook call We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request

Body

These parameters are returned in the body of the webhook_callback_url.

Parameter	Type	Always returned?	Sample Value	Description
task_id	String	yes	t_123456	The task id associated with this specific task
status	String	yes	success	The status of the task
extracted_information	Object	Yes	’price’: ‘$100.0’	Unstructured JSON payload containing the extracted information as specified by the users’ input prompt
screenshot_url	String	Yes	… url to screenshot …	Screenshot of the final page, where the data extraction occurs
recording_url	String	Yes	.. url to recording …	Recording of the entire browsing session to help debug any issues
failure_reason	String	No	“Failed to pass this page - missing information: date of birth”	A failure reason that caused the job to fail. This can range from internal errors (Skyvern side) or external errors (insufficient information provided)

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:api.skyvern.com/api/v1/tasks/{task_id}

Parameter	Type	Required?	Sample Value	Description
task_id	String	yes	t_123	The id of the task you want to check the status of

Request - List Task Details (GET)

Request type: GET

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

Parameter	Type	Required?	Sample Value	Description
page	Integer	no	1	default=1
has to be ≥1
page_size	Integer	no	10	default=10
has to be ≥1

Response - Task Details (GET)

Parameter	Type	Sample Value	Description
request	JSON		Includes the initial request sent to create the task. Fields included: url,webhook_callback_url,navigation_goal,data_extraction_goal,navigation_payload,proxy_location,extracted_information_schema
task_id	String	tsk_123	The id of the task you want to check the status of
status	String	created / queued / running / completed / terminated / failed / canceled	String indicating the status of this task. created: the initial state when the task is created; queued: the task has been enqueued and is waiting to be picked up by a worker to execute; running: the task is being executed; completed: the task has successfully completed; terminated: the agent doesn’t believe the task could be completed so it terminated the task; failed: the task failed due to a specific reason; canceled: the task is canceled by the user
created_at	Timestamp	2022-11-22T22:55:55	Timestamp indicating when the task was created.
modified_at	Timestamp	2022-11-22T22:55:55	Timestamp indicating when the task was last updated. Used to detect long-running tasks.
extracted_information	Object	’price’: ‘$100.0’
screenshot_url	String	”https://skyvern-artifacts.s3.amazonaws.com/production/tsk_123/…screenshot_final.png”	… url to screenshot …
recording_url	String	”https://skyvern-artifacts.s3.amazonaws.com/production/tsk_123/…recording.webm”	… url to recording …
action_screenshot_urls	List[str]	[“https://skyvern-artifacts.s3.amazonaws.com/production/tsk_123/step_2…action.png”, “https://skyvern-artifacts.s3.amazonaws.com/production/tsk_123/step_0…action.png”, “https://skyvern-artifacts.s3.amazonaws.com/production/tsk_123/step_0…action.png”]	3 screenshots for the lastest 3 actions that Skyvern took.
failure_reason	String	“Failed to pass this page - missing information: invalid password”	The reason why the task failed. Examples: “Max steps per task (10) exceeded …” - by default, a task as a cap on the number of steps per task for budget control. This can be configured in your organization settings page; “Max retries per step (3) exceeded…” - this means Skyvern ran into some internal failures. Skyvern Agent is not perfect and doesn’t have 100% web coverage today. When it runs into pages it cannot navigate through or take actions on, this failure_reason shows up. (Currently we’re improving Skyvern’s abilility as well as the failure_reason to show better errors to help generate better feedbacks to your failure)

Request - List Steps (GET)

Each task 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 task.

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

Step Object

Parameter	Type	Sample Value	Description
organization_id	String	o_123	Your organization id
task_id	String	tsk_123	The id of the task
step_id	String	stp_123	The id of the step
status	String	created / running / completed / failed / canceled	The status of the step
order	Integer	0 / 1 / 2	The zero based index of the step. 0 is the first step of the task.
retry_index	Integer	0 / 1 / 2 / 3	When a step fails, the retry step will have a retry_index that’s larger than 0
input_token_count	Integer	19223	The number of input tokens used in this step
output_token_count	Integer	500	The number of output tokens generated in this step

Request - Cancel A Task (POST)

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

Request type: POST

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