# Skyvern

> Automate browser interactions with AI. Run tasks with natural language prompts, create reusable workflows, and extract structured data from web pages.

Source: https://cotera.co/docs/reference/tools/individual-tools/skyvern

---

**Authentication Type:** API Key

**Description:** Automate browser interactions with AI. Run tasks with natural language prompts, create reusable workflows, and extract structured data from web pages.

> **Beta Tool:** Please contact support to get this Beta tool added to your account.

***

## Authentication

To authenticate, you'll need a Skyvern API key from [Skyvern](https://app.skyvern.com/settings).

Use the `x-api-key` header for authentication.

***

## Tasks

### Run Task

Run a browser automation task with a natural language prompt.

**Operation Type:** Mutation (Write)

**Parameters:**

* **prompt** `string` (required): Task description for the agent to accomplish
* **url** `string` (optional): Starting URL. Auto-determined if omitted.
* **engine** `string` (optional, default: "skyvern-2.0"): Execution engine (skyvern-1.0, skyvern-2.0, openai-cua, anthropic-cua, ui-tars)
* **title** `string` (optional): Task label
* **proxy\_location** `string/object` (optional): Geographic routing (RESIDENTIAL, US-CA, RESIDENTIAL\_ES, etc.)
* **data\_extraction\_schema** `object` (optional): JSON Schema for structured output
* **error\_code\_mapping** `object` (optional): Custom error code mappings
* **max\_steps** `number` (optional): Step limit before auto-failure
* **webhook\_url** `string` (optional): Completion notification endpoint
* **totp\_identifier** `string` (optional): 2FA code identifier
* **totp\_url** `string` (optional): Endpoint serving TOTP codes
* **browser\_session\_id** `string` (optional): Reuse existing browser session
* **publish\_workflow** `boolean` (optional): Create reusable workflow (skyvern-2.0 only)

**Returns:**

* **run\_id** `string`: Unique run identifier (tsk\* or wr\* prefix)
* **status** `string`: Status (created, queued, running, completed, failed, timed\_out, terminated, canceled)
* **output** `object/array/string` (nullable): Extracted data
* **downloaded\_files** `array`: File metadata with URLs
* **recording\_url** `string` (nullable): Execution video link
* **screenshot\_urls** `array`: Latest screenshots
* **failure\_reason** `string` (nullable): Error details if failed
* **app\_url** `string` (nullable): UI link for viewing execution
* **step\_count** `number` (nullable): Total steps executed

**Example Usage:**

```json
{
  "prompt": "Go to LinkedIn and search for software engineers in San Francisco. Extract the first 10 results with their name, title, and company.",
  "url": "https://linkedin.com",
  "data_extraction_schema": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "title": { "type": "string" },
        "company": { "type": "string" }
      }
    }
  },
  "max_steps": 50
}
```

### Get Run

Check the status and retrieve results of a Skyvern task run.

**Operation Type:** Query (Read)

**Parameters:**

* **run\_id** `string` (required): The run ID returned from Run Task or Run Workflow (tsk\* or wr\* prefix)

**Returns:**

* **run\_id** `string`: Unique run identifier
* **status** `string`: Current status (created, queued, running, completed, failed, timed\_out, terminated, canceled)
* **output** `object/array/string` (nullable): Extracted data if completed
* **downloaded\_files** `array`: File metadata with URLs
* **recording\_url** `string` (nullable): Execution video link
* **screenshot\_urls** `array`: Latest screenshots
* **failure\_reason** `string` (nullable): Error details if failed
* **app\_url** `string` (nullable): UI link for viewing execution
* **step\_count** `number` (nullable): Total steps executed

**Example Usage:**

```json
{
  "run_id": "tsk_abc123xyz"
}
```

***

## Workflows

### Create Workflow

Create a reusable workflow with defined steps and parameters.

**Operation Type:** Mutation (Write)

**Parameters:**

* **title** `string` (required): Workflow name
* **workflow\_definition** `object` (required): Workflow configuration
  * **parameters** `array`: Input parameters
  * **blocks** `array`: Workflow steps (task, code, navigation, extraction, login, conditional, for\_loop, etc.)
* **description** `string` (optional): Workflow description
* **proxy\_location** `string` (optional): Default proxy location
* **webhook\_callback\_url** `string` (optional): Default webhook URL

**Returns:**

* **workflow\_id** `string`: Unique workflow identifier (wpid\_ prefix)
* **status** `string`: Creation status

**Example Usage:**

```json
{
  "title": "LinkedIn Lead Scraper",
  "workflow_definition": {
    "parameters": [
      { "key": "search_query", "type": "string" },
      { "key": "max_results", "type": "number", "default": 10 }
    ],
    "blocks": [
      {
        "type": "task",
        "prompt": "Search LinkedIn for {{search_query}} and extract {{max_results}} profiles"
      }
    ]
  }
}
```

### Run Workflow

Execute a saved workflow with custom parameters.

**Operation Type:** Mutation (Write)

**Parameters:**

* **workflow\_id** `string` (required): Workflow ID (wpid\_ prefix)
* **parameters** `object` (optional): Custom input values
* **title** `string` (optional): Display name for this execution
* **proxy\_location** `string/object` (optional): Geographic routing override
* **webhook\_url** `string` (optional): Override webhook URL
* **browser\_session\_id** `string` (optional): Reuse existing browser session
* **browser\_profile\_id** `string` (optional): Reuse browser profile

**Returns:**

* **run\_id** `string`: Unique run identifier (wr\_ prefix)
* **status** `string`: Execution status
* **output** `object/array/string` (nullable): Extracted data
* **recording\_url** `string` (nullable): Execution video
* **app\_url** `string` (nullable): UI link

**Example Usage:**

```json
{
  "workflow_id": "wpid_abc123xyz",
  "parameters": {
    "search_query": "AI engineers",
    "max_results": 25
  },
  "title": "AI Engineers Search - January 2024"
}
```

### Update Workflow

Update an existing workflow definition.

**Operation Type:** Mutation (Write)

**Parameters:**

* **workflow\_id** `string` (required): Workflow ID to update
* **title** `string` (optional): Updated title
* **workflow\_definition** `object` (optional): Updated workflow configuration
* **description** `string` (optional): Updated description

**Returns:**

Updated workflow object.

***

## Common Use Cases

**Web Scraping:**

* Extract structured data from websites with natural language
* Scrape listings, directories, and search results
* Handle dynamic JavaScript-rendered content

**Form Automation:**

* Fill out web forms programmatically
* Submit applications and registrations
* Handle multi-step form workflows

**Data Entry:**

* Automate repetitive data entry tasks
* Copy data between web applications
* Sync information across platforms

**Testing & Monitoring:**

* Run automated browser tests
* Monitor website availability and functionality
* Capture screenshots and recordings for debugging