Dorod-Sky/fern/running-tasks/api-spec.mdx

---
title: Tasks API
subtitle: The core building block in Skyvern
slug: running-tasks/api-spec
---

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`

### 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 |

### Body

| Parameter | Type | Required? | Sample Value | Description |
| --- | --- | --- | --- | --- |
| prompt | String | yes | "Apply for a job" | The goal or task description for Skyvern to accomplish |
| url | String | no | https://www.example.com | The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL |
| title | String | no | "Job Application Task" | Optional title for the task |
| engine | String | no | "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_location | String | no | "RESIDENTIAL" | Geographic Proxy location to route the browser traffic through. Default is "RESIDENTIAL" |
| data_extraction_schema | Object | no | \{ "success": \{ "type": "boolean" } } | Schema defining what data should be extracted from the webpage |
| error_code_mapping | Object | no | \{ "AUTH_FAILED": "Authentication failed" } | Custom mapping of error codes to error messages if Skyvern encounters an error |
| max_steps | Integer | no | 10 | Maximum number of steps the task can take before timing out |
| webhook_url | String | no | https://api.example.com/webhook | URL to send task status updates to after a run is finished |
| totp_identifier | String | no | "user@example.com" | Identifier for TOTP (Time-based One-Time Password) authentication if codes are being pushed to Skyvern |
| totp_url | String | no | https://api.example.com/totp | URL for TOTP authentication setup if Skyvern should be polling endpoint for 2FA codes |
| browser_session_id | String | no | "sess_123" | ID of an existing browser session to reuse, having it continue from the current screen state |
| publish_workflow | Boolean | no | false | Whether to publish this task as a reusable workflow. Default is false |

## Example Request (Apply for a job)

```python
POST https://api.skyvern.com/v1/run/tasks

{
    "prompt": "Apply for a job on behalf of this person: name: Chris P Bacon. email: chris@pbacon.com",
    "url": "https://jobs.lever.co/leverdemo-8/45d39614-464a-4b62-a5cd-8683ce4fb80a/apply",
    "title": "Job Application Task",
    "engine": "skyvern-2.0",
    "proxy_location": "RESIDENTIAL",
    "data_extraction_schema": {
        "application_success": {
            "type": "boolean"
        }
    }
}
```

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

| Parameter | Type | Always returned? | Sample Value | Description |
| --- | --- | --- | --- | --- |
| run_id | String | yes | "t_123456" or "oc_12345" | Unique identifier for this run |
| status | String | yes | "running" | Current status of the run. Possible values: "created", "queued", "running", "timed_out", "failed", "terminated", "completed", "canceled" |
| output | Object/Array/String/null | no | \{ "success": true } | Output data from the run, if any. Format depends on the schema in the input |
| downloaded_files | Array/null | no | [\{ "url": "...", "checksum": "...", "filename": "..." }] | List of files downloaded during the run |
| recording_url | String | no | "https://..." | URL to the recording of the run |
| failure_reason | String | no | "Max steps exceeded" | Reason for failure if the run failed |
| created_at | String | yes | "2024-03-20T10:00:00Z" | Timestamp when this run was created |
| modified_at | String | yes | "2024-03-20T10:05:00Z" | Timestamp when this run was last modified |
| run_type | String | yes | "task_v2" | Type of task run - either task_v1 or task_v2 |
| run_request | Object | yes | \{...} | 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}`

| Parameter | Type | Required? | Sample Value | Description |
| --- | --- | --- | --- | --- |
| run_id | String | yes | "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/`

| 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)
Production: `https://api.skyvern.com/v1/runs/{run_id}`

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

| Parameter | Type | Sample Value | Description |
| --- | --- | --- | --- |
| run_id | String | "t_123456" | Unique identifier for this run |
| status | String | "created" | Current status of the run. Possible values: "created", "queued", "running", "timed_out", "failed", "terminated", "completed", "canceled" |
| output | Object | \{ "additionalProp1": \{ } } | Output data from the run |
| downloaded_files | Array | [\{ "url": "string", "checksum": "string", "filename": "string" }] | List of files downloaded during the run |
| recording_url | String | "https://..." | URL to the recording of the run |
| failure_reason | String | "Max steps exceeded" | Reason for failure if the run failed |
| created_at | String | "2025-04-03T14:08:29.505Z" | Timestamp when this run was created |
| modified_at | String | "2025-04-03T14:08:29.505Z" | Timestamp when this run was last modified |
| run_type | String | "task_v1" | Type of task run - either task_v1 or task_v2 |
| run_request | Object | \{ "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
| 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 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`