​
Request - Initiate a task

Request type: POST

Production:https://api.skyvern.com/api/v2/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
x-max-iterations-overrideIntegerno10The max number of iterations skyvern attempts to divide and conquer a complicated task. In each iteration, Skyvern does a “mini task” planning, mini task execution and validation. The default is 10.

​
Body

ParameterTypeRequired?Sample ValueDescription
user_promptStringyesFind a route between Chicago to Los Angeles on google maps, then print the route details.
urlHttpUrlnohttps://www.google.com/maps/If you want to use a specific url, you can pass it here. It’s optional since you can also tell skyvern which site to go to in the user_prompt.
webhook_callback_urlHttpUrlnohttps://mywebsite.com/webhookThe callback URL once our system is finished processing this async task
proxy_locationStringnoRESIDENTIALProxy location for the web-browsing request. Please pass RESIDENTIAL as a value
totp_verification_urlHttpUrlnohttps://mywebsite.com/two_factor_codeThe 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_identifierStringnomyemail@example.com / 4155558888The 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)

POST https://api.skyvern.com/api/v2/tasks/ 

{
    "user_prompt": "Find a route between Chicago to Los Angeles on google maps, then print the route details.",
    "proxy_location": "RESIDENTIAL"
}

​
Response

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

ParameterTypeAlways returned?Sample ValueDescription
task_idStringyest_123456The task id associated with this specific task
statusStringyescreatedThe status of the task
promptStringyesFind a route between Chicago to Los Angeles on google maps, then print the route details.
urlHttpUrlyeshttps://www.google.com/maps/The url that skyvern starts browsing with
organization_idStringyeso_123456The organization id associated with this task
workflow_idStringyeswf_123456The workflow id created by this task
workflow_run_idStringyeswr_123456The ID of the workflow run
workflow_permanent_idStringyeswpid_123456The workflow permanent id
summaryStringnoThe user has successfully found routes between Chicago and Los Angeles on Google Maps. The extracted details include travel modes, travel times, distances, route descriptions, and additional information for each route.The summary of what skyvern did.
outputObjectno{ "routes": [{"travel_mode": "Driving", "travel_time": "30 hr", "distance": "2,015 miles", "route_description": "via I-80 W", "additional_info": ["28 hr without traffic", "This route has tolls", "Your destination is in a different time zone"]}] }The output of the task. This is the structured data that skyvern extracted from the website.
webhook_callback_urlHttpUrlnohttps://mywebsite.com/webhookThe url of your webhook endpoint if sent to execute the task.
totp_verification_urlHttpUrlnohttps://mywebsite.com/two_factor_codeThe url of your TOTP endpoint if sent to execute the task.
totp_identifierStringnomyemail@example.com / 4155558888The totp_identifier sent to execute the task.
proxy_locationStringnoRESIDENTIALThe proxy location used to execute the task.
created_atTimestampyes2022-11-22T22:55:55The timestamp when the task was created.
modified_atTimestampyes2022-11-22T22:55:55The timestamp when the task was last updated.

​
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

ParameterTypeRequired?Sample ValueDescription
x-skyvern-signatureStringyesv0=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-timestampStringyes1531420618Timestamp 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 sent in the body of the request to webhook_callback_url.

Here’s an example of the webhook body:

{
    "task_id": "oc_347318612592634222",
    "status": "completed",
    "organization_id": "o_123456",
    "workflow_run_id": "wr_123456",
    "workflow_id": "w_123456",
    "workflow_permanent_id": "wpid_123456",
    "prompt": "Find a route between Chicago to Los Angeles on google maps, then print the route details.",
    "url": "https://www.google.com/maps/",
    "summary": "The user has successfully found routes between Chicago and Los Angeles on Google Maps. The extracted details include travel modes, travel times, distances, route descriptions, and additional information for each route.",
    "output": {
      "routes": [
        {
          "travel_mode": "Driving",
          "travel_time": "30 hr",
          "distance": "2,015 miles",
          "route_description": "via I-80 W",
          "additional_info": [
            "28 hr without traffic",
            "This route has tolls.",
            "Your destination is in a different time zone."
          ]
        },
        {
          "travel_mode": "Driving",
          "travel_time": "30 hr",
          "distance": "2,028 miles",
          "route_description": "via I-80 W and I-70 W",
          "additional_info": [
            "28 hr without traffic"
          ]
        },
        {
          "travel_mode": "Flights",
          "travel_time": "4 hr 30 min",
          "distance": null,
          "route_description": "Chicago, IL—Los Angeles, CA",
          "additional_info": [
            "from $150"
          ]
        }
      ],
      "extraction_datetime": "2025-01-10T22:56:20.297774Z"
    },
    "totp_verification_url": null,
    "totp_identifier": null,
    "proxy_location": null,
    "webhook_callback_url": null,
    "created_at": "2025-01-10T22:53:36.297774Z",
    "modified_at": "2025-01-10T22:56:29.582779Z"
}
Tasks APIWebhooks FAQ