API Quickstart

Run your first browser automation in 5 minutes. By the end of this guide, you’ll scrape the top post from Hacker News using Skyvern’s AI agent.

Prefer a visual interface? Try the Cloud UI instead — no code required.

Step 1: Get your API key

Sign up at app.skyvern.com and go to Settings to copy your API key. When you make API calls, Skyvern spins up a cloud browser, executes your task with AI, and returns the results. You can watch the browser live at any time.

Step 2: Install the SDK

pip install skyvern

Troubleshooting: Python version errors

The Skyvern SDK requires Python 3.11, 3.12, or 3.13. If you encounter version errors, try using pipx:

pipx install skyvern

pipx installs Python packages in isolated environments while making them globally available.

Step 3: Run your first task

Let’s scrape the title of the #1 post on Hacker News. You only need two parameters:

prompt — Natural language instructions for what the AI should do. Be specific about the data you want extracted.
url — The starting page. Skyvern’s AI will navigate from here based on your prompt.

The SDK uses async/await because Skyvern spins up a cloud browser and executes your task remotely, which can take 30-60 seconds.

import os
import asyncio
from skyvern import Skyvern

async def main():
    client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))

    result = await client.run_task(
        prompt="Go to news.ycombinator.com and get the title of the #1 post",
        url="https://news.ycombinator.com",
    )

    print(f"Run ID: {result.run_id}")
    print(f"Status: {result.status}")

asyncio.run(main())

The response includes a run_id you’ll use to check status and fetch results.

Step 4: Check the status

Since tasks run asynchronously, you have two options:

Polling — Periodically check the task status (shown below)
Webhooks — Get notified when the task completes (see webhooks guide)

The code below polls every 5 seconds until the task reaches a terminal state. Once complete, run.output contains the extracted data as a dictionary.

import os
import asyncio
from skyvern import Skyvern

async def main():
    client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))

    result = await client.run_task(
        prompt="Go to news.ycombinator.com and get the title of the #1 post",
        url="https://news.ycombinator.com",
    )

    run_id = result.run_id
    print(f"Task started: {run_id}")

    while True:
        run = await client.get_run(run_id)
        print(f"Status: {run.status}")

        if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
            break

        await asyncio.sleep(5)

    print(f"Final status: {run.status}")
    print(f"Output: {run.output}")

asyncio.run(main())

Run states:

created — Task initialized, not yet queued
queued — Waiting for an available browser
running — AI is navigating and executing
completed — Task finished successfully
failed — Task encountered an error
terminated — Task was manually stopped
timed_out — Task exceeded time limit
canceled — Task was cancelled before starting

Step 5: View your results

When the task completes, you’ll get a response like this:

{
  "run_id": "tsk_v2_486305187432193504",
  "status": "completed",
  "output": {
    "top_post_title": "Linux kernel framework for PCIe device emulation, in userspace"
  },
  "downloaded_files": [],
  "recording_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/.../recording.webm?...",
  "screenshot_urls": ["https://skyvern-artifacts.s3.amazonaws.com/v1/production/.../screenshot_final.png?..."],
  "app_url": "https://app.skyvern.com/runs/wr_486305187432193510",
  "step_count": 2,
  "run_type": "task_v2"
}

The output contains whatever data the AI extracted based on your prompt. The app_url links to the Cloud UI where you can view the full run details.

Step 6: Watch the recording

Every task is recorded. There are two ways to access recordings:

From the API response

The recording_url field is included in every completed run response:

{
  "run_id": "tsk_v2_486305187432193504",
  "status": "completed",
  "recording_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/o_485917350850524254/tsk_.../recording.webm?AWSAccessKeyId=...&Signature=...&Expires=..."
}

From the Cloud UI

Navigate to Runs and click on your run to see the Recording tab.

What you’ll see

Live browser view — Watch the AI navigate in real-time
Recording — Full video replay of the session
Actions — Step-by-step breakdown with screenshots
AI Reasoning — See why the AI made each decision

This is invaluable for debugging and understanding how Skyvern interprets your prompts.

Run with a local browser

You can run Skyvern with a browser on your own machine. This is useful for development, debugging, or automating internal tools on your local network. Prerequisites:

Skyvern SDK installed (pip install skyvern)
PostgreSQL database (local install or Docker)
An LLM API key (OpenAI, Anthropic, Azure OpenAI, Gemini, Ollama, or any OpenAI-compatible provider)

Docker is optional. If you have PostgreSQL installed locally, Skyvern will detect and use it automatically. Use skyvern init --no-postgres to skip database setup entirely if you’re managing PostgreSQL separately.

Set up local Skyvern

# Run this from your app or repo root if you want Claude Code + /qa set up in-place
skyvern quickstart

# Or use setup-only mode if you do not want to start services yet
skyvern init

Skyvern init interactive setup wizard

This interactive wizard will:

Set up your database (detects local PostgreSQL or uses Docker)
Configure your LLM provider
Choose browser mode (headless, headful, or connect to existing Chrome)
Generate local API credentials
Optionally configure local MCP for Claude Code, Claude Desktop, Cursor, or Windsurf
Download the Chromium browser

If you choose Claude Code during the MCP step and you run the wizard inside a project or repo, Skyvern will:

write a project-local .mcp.json
pin the MCP command to the active Python interpreter (/path/to/python -m skyvern run mcp)
install bundled Claude Code skills into .claude/skills/, including /qa
keep the whole path local, so Claude Code can test localhost directly without Skyvern Cloud or browser tunneling

This will generate a .env file that stores your local configuration, LLM api keys and your local BASE_URL and SKYVERN_API_KEY:

ENV='local'
ENABLE_OPENAI='true'
OPENAI_API_KEY='<API_KEY>'
...
LLM_KEY='OPENAI_GPT4O'
SECONDARY_LLM_KEY=''
BROWSER_TYPE='chromium-headful'
MAX_SCRAPING_RETRIES='0'
VIDEO_PATH='./videos'
BROWSER_ACTION_TIMEOUT_MS='5000'
MAX_STEPS_PER_RUN='50'
LOG_LEVEL='INFO'
LITELLM_LOG='CRITICAL'
DATABASE_STRING='postgresql+psycopg://skyvern@localhost/skyvern'
PORT='8000'
...
SKYVERN_BASE_URL='http://localhost:8000'
SKYVERN_API_KEY='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjQ5MTMzODQ2MDksInN1YiI6Im9fNDg0MjIwNjY3MzYzNzA2Njk4In0.Crwy0-y7hpMVSyhzNJGzDu_oaMvrK76RbRb7YhSo3YA'

Start the local server

If you used skyvern quickstart and chose to start services, Skyvern is already running. If you used skyvern init, start the server with:

skyvern run server

Skyvern local server logs

Run a task locally

The only difference from cloud is the base_url parameter pointing to your local server. The API is identical, so the same code works in both environments — develop locally, deploy to cloud without changes.

import os
import asyncio
from skyvern import Skyvern

async def main():
    client = Skyvern(
        base_url="http://localhost:8000",
        api_key=os.getenv("SKYVERN_API_KEY")
    )

    result = await client.run_task(
        prompt="Go to news.ycombinator.com and get the title of the #1 post",
        url="https://news.ycombinator.com",
    )

    print(f"Run ID: {result.run_id}")

asyncio.run(main())

A browser window will open on your machine (if you chose headful mode). Recordings and logs are saved in the directory where you started the server. If you also selected Claude Code during setup, start your local frontend dev server and run /qa http://localhost:3000 in Claude Code to validate the app against your local environment.

Next steps

Extract Structured Data

Define a schema to get typed JSON output from your automations

Handle Logins

Store credentials securely for sites that require authentication

Build Workflows

Chain multiple steps together for complex automations

Use Webhooks

Get notified when tasks complete instead of polling

Getting Started

Running Automations

Multi-Step Automations

Optimization

Going to Production

Debugging

Self-Hosted Deployment

Step 1: Get your API key

Step 2: Install the SDK

Step 3: Run your first task

Step 4: Check the status

Step 5: View your results

Step 6: Watch the recording

From the API response

From the Cloud UI

What you’ll see

Run with a local browser

Set up local Skyvern

Start the local server

Run a task locally

Next steps

Extract Structured Data

Handle Logins

Build Workflows

Use Webhooks

Getting Started

Running Automations

Multi-Step Automations

Optimization

Going to Production

Debugging

Self-Hosted Deployment

​Step 1: Get your API key

​Step 2: Install the SDK

​Step 3: Run your first task

​Step 4: Check the status

​Step 5: View your results

​Step 6: Watch the recording

​From the API response

​From the Cloud UI

​What you’ll see

​Run with a local browser

​Set up local Skyvern

​Start the local server

​Run a task locally

​Next steps

Extract Structured Data

Handle Logins

Build Workflows

Use Webhooks

Step 1: Get your API key

Step 2: Install the SDK

Step 3: Run your first task

Step 4: Check the status

Step 5: View your results

Step 6: Watch the recording

From the API response

From the Cloud UI

What you’ll see

Run with a local browser

Set up local Skyvern

Start the local server

Run a task locally

Next steps