---
title: Tasks API V2
description: 'The latest version of Skyvern agent task, with better reasoning and validation'
---

## Request - Initiate a task 
Request type: `POST`

Production:`https://api.skyvern.com/api/v2/tasks/`

### Header 

| 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-iterations-override | Integer | no | 10 | The 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

| Parameter | Type | Required? | Sample Value | Description |
| --- | --- | --- | --- | --- |
| user_prompt | String | yes | 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 |
| url | HttpUrl | no | https://www.example.com | 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_url | HttpUrl | no | …  | The callback URL once our system is finished processing this async task |
| proxy_location | String | no | RESIDENTIAL | Proxy location for the web-browsing request. Please pass RESIDENTIAL as a value |
| 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](https://docs.skyvern.com/running-tasks/advanced-features#push-code-to-skyvern) |

## Example Request (Apply for a job)

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

{
    "user_prompt": "Apply for a job at https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply. Name: Chris P. Bacon, Email: chris@pbacon.com",
    "proxy_location": "RESIDENTIAL"
}
```

## 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 |
| status | String | yes | created | The status of the task |
| prompt | String | yes | Apply for a job at https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply. Name: Chris P. Bacon, Email: chris@pbacon.com | The user_prompt that skyvern received. |
| url | HttpUrl | yes | https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply | The url that skyvern starts browsing with |
| organization_id | String | yes | o_123456 | The organization id associated with this task |
| workflow_id | String | yes | wf_123456 | The workflow id created by this task |
| workflow_run_id | String | yes | wr_123456 | The ID of the workflow run |
| workflow_permanent_id | String | yes | wpid_123456 | The workflow permanent id |
| summary | String | no | The summary of what skyvern did when the task is completed |
| output | Object | no | { "name": "Chris P. Bacon", "email": "chris@pbacon.com" } | The output of the task. This is the structured data that skyvern extracted from the website. |
| webhook_callback_url | HttpUrl | no | https://mywebsite.com/webhook | The url of your webhook endpoint if sent to execute the task. |
| totp_verification_url | HttpUrl | no | https://mywebsite.com/two_factor_code | The url of your TOTP endpoint if sent to execute the task. |
| totp_identifier | String | no | myemail@example.com / 4155558888 | The totp_identifier sent to execute the task.|
| proxy_location | String | no | RESIDENTIAL | The proxy location used to execute the task. |
| created_at | Timestamp | yes | 2022-11-22T22:55:55 | The timestamp when the task was created. |
| modified_at | Timestamp | yes | 2022-11-22T22:55:55 | The 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

| Parameter | Type | Required? | Sample Value | Description |
| --- | --- | --- | --- | --- |
| x-skyvern-signature | String | yes | v0=a2114d57b48eac39b9ad189<br/>dd8316235a7b4a8d21a10bd275<br/>19666489c69b503 | Authentication token that allows our service to communicate with your backend service via callback / webhook <br/>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<br/><br/>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": "Apply for a job at https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply. Name: Chris P. Bacon, Email: chris@pbacon.com",
    "url": "https://www.coursera.org/",
    "summary": "The user successfully applied for a job.",
    "output": null,
    "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"
}
```