Skip to main content

Documentation Index

Fetch the complete documentation index at: https://skyvern.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Skyvern SDK wraps the REST API in a typed client with built-in browser automation via Playwright.

​
Install

# Requires Python 3.11+
pip install skyvern
If you hit Python version errors, use pipx install skyvern to install in an isolated environment.

​
Initialize the client

Create a Skyvern instance with your API key. All methods are async. 
import asyncio
from skyvern import Skyvern

async def main():
    # All methods are coroutines - wrap in async and use asyncio.run()
    # If inside FastAPI/Django ASGI, await directly without asyncio.run()
    client = Skyvern(api_key="YOUR_API_KEY")

    result = await client.run_task(
        prompt="Get the title of the top post on Hacker News",
        url="https://news.ycombinator.com",
        wait_for_completion=True,
    )
    print(result.output)

asyncio.run(main())

​
Constructor parameters

ParameterTypeDefaultDescription
api_key / apiKeystr / string-Required. Your Skyvern API key. Get one at app.skyvern.com/settings.
environmentSkyvernEnvironmentCLOUD / CloudTarget environment. See Environments.
base_url / baseUrlstr / stringNoneOverride the API base URL for self-hosted deployments.
timeout / timeoutInSecondsfloat / numberNone / 60HTTP request timeout in seconds.
max_retries / maxRetriesint / numberNone / 2Number of times to retry failed requests.
headersdict / Record<string, string>NoneAdditional headers included with every request.
ParameterTypeDefaultDescription
follow_redirectsboolTrueWhether to follow HTTP redirects.
httpx_clienthttpx.AsyncClientNoneProvide your own httpx client for custom TLS, proxying, or connection pooling.

​
Environments

Three built-in environment URLs: 
from skyvern.client import SkyvernEnvironment
EnvironmentURLWhen to use
CLOUD / Cloudhttps://api.skyvern.comSkyvern Cloud (default)
STAGING / Staginghttps://api-staging.skyvern.comStaging environment
LOCAL / Localhttp://localhost:8000Local server started with skyvern run server
For a self-hosted instance at a custom URL: 
client = Skyvern(
    api_key="YOUR_API_KEY",
    base_url="https://skyvern.your-company.com",
)

​
Local mode

Run Skyvern entirely on your machine - no cloud, no network calls. Skyvern.local() reads your .env file, boots the engine in-process, and connects the client to it. Prerequisite: Run skyvern quickstart once to create the .env file with your database connection and LLM API keys. 
from skyvern import Skyvern

# Python only. TypeScript requires a running Skyvern server
client = Skyvern.local()

result = await client.run_task(
    prompt="Get the title of the top post",
    url="https://news.ycombinator.com",
    wait_for_completion=True,
)
If you configured headful mode during skyvern quickstart, a Chromium window opens so you can watch the AI work.
ParameterTypeDefaultDescription
llm_configLLMConfig | LLMRouterConfig | NoneNoneOverride the LLM. If omitted, uses LLM_KEY from .env.
settingsdict | NoneNoneOverride .env settings at runtime. Example: {"MAX_STEPS_PER_RUN": 100}

​
Waiting for completion

By default, task and workflow runs return immediately after queuing. You get a run ID and need to poll for results yourself. Pass wait_for_completion to have the SDK poll automatically until the run reaches a terminal state (completed, failed, terminated, timed_out, or canceled): 
# Returns only after the task finishes (up to 30 min by default)
result = await client.run_task(
    prompt="Fill out the contact form",
    url="https://example.com/contact",
    wait_for_completion=True,
    timeout=600,  # give up after 10 minutes
)

# Without wait_for_completion -- returns immediately
task = await client.run_task(
    prompt="Fill out the contact form",
    url="https://example.com/contact",
)
print(task.run_id)  # poll with client.get_run(task.run_id)
ParameterTypeDefaultDescription
wait_for_completion / waitForCompletionbool / booleanfalsePoll until the run finishes.
timeoutfloat / number1800Maximum wait time in seconds.
Supported on task runs, workflow runs, and login. In TypeScript, also supported on file downloads.

​
Request options

Every method accepts per-request overrides for timeout, retries, and headers: 
from skyvern.client.core import RequestOptions

result = await client.run_task(
    prompt="Extract data",
    url="https://example.com",
    request_options=RequestOptions(
        timeout_in_seconds=120,
        max_retries=3,
        additional_headers={"x-custom-header": "value"},
    ),
)
OptionTypeDescription
timeout_in_seconds / timeoutInSecondsint / numberHTTP timeout for this request.
max_retries / maxRetriesint / numberRetry count for this request.
additional_headers / headersdict / Record<string, string>Extra headers for this request.
additional_query_parametersdictExtra query parameters (Python only).
additional_body_parametersdictExtra body parameters (Python only).
abortSignalAbortSignalSignal to abort the request (TypeScript only).
apiKeystringOverride the API key for this request (TypeScript only).
These override the client-level defaults for that single call only.

​
Next steps

Browser Automation

Control browsers with Playwright + AI

Tasks

Run browser automations with run_task

Workflows

Create and run multi-step automations

Error Handling

Handle errors and configure retries