Skip to main content
The @skyvern/client package wraps the Skyvern REST API in a typed TypeScript client with built-in browser automation via Playwright. 
npm install @skyvern/client
Requires Node.js 18+. Also compatible with Bun, Deno, and Cloudflare Workers.

​
Initialize the client

The Skyvern class provides both API methods and browser automation. All API methods return promises: 
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });

const result = await skyvern.runTask({
  body: {
    prompt: "Get the title of the top post on Hacker News",
    url: "https://news.ycombinator.com",
  },
  waitForCompletion: true,
});
console.log(result.output);

​
Constructor parameters

ParameterTypeDefaultDescription
apiKeystring—Required. Your Skyvern API key. Get one at app.skyvern.com/settings.
environmentSkyvernEnvironment | stringCloudTarget environment. Options: Cloud, Staging, Local.
baseUrlstringundefinedOverride the API base URL. Use this for self-hosted deployments.
timeoutInSecondsnumber60HTTP request timeout in seconds.
maxRetriesnumber2Number of times to retry failed requests.
headersRecord<string, string>undefinedAdditional headers included with every request.

​
Environments

The SDK ships with three built-in environment URLs: 
import { SkyvernEnvironment } from "@skyvern/client";
EnvironmentURLWhen to use
SkyvernEnvironment.Cloudhttps://api.skyvern.comSkyvern Cloud (default)
SkyvernEnvironment.Staginghttps://api-staging.skyvern.comStaging environment
SkyvernEnvironment.Localhttp://localhost:8000Local server started with skyvern run server
For a self-hosted instance at a custom URL, pass baseUrl instead: 
const skyvern = new Skyvern({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://skyvern.your-company.com",
});

​
waitForCompletion

By default, runTask and runWorkflow return immediately after the run is queued — you get a run_id and need to poll getRun() yourself. Pass waitForCompletion: true 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)
const result = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form",
    url: "https://example.com/contact",
  },
  waitForCompletion: true,
  timeout: 600, // give up after 10 minutes
});

// Without waitForCompletion — returns immediately
const task = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form",
    url: "https://example.com/contact",
  },
});
console.log(task.run_id); // poll with skyvern.getRun(task.run_id)
ParameterTypeDefaultDescription
waitForCompletionbooleanfalsePoll until the run finishes.
timeoutnumber1800Maximum wait time in seconds. Throws Error if exceeded.
Supported on runTask, runWorkflow, login, and downloadFiles.

​
Request options

Every method accepts an optional second parameter for per-request overrides of timeout, retries, headers, and abort signal: 
const result = await skyvern.runTask(
  {
    body: {
      prompt: "Extract data",
      url: "https://example.com",
    },
  },
  {
    timeoutInSeconds: 120,
    maxRetries: 3,
    headers: { "x-custom-header": "value" },
  },
);
ParameterTypeDescription
timeoutInSecondsnumberHTTP timeout for this request.
maxRetriesnumberRetry count for this request.
abortSignalAbortSignalSignal to abort the request.
apiKeystringOverride the API key for this request.
headersRecord<string, string>Additional headers for this request.
These override the client-level defaults for that single call only.

​
Next steps

Tasks

Run browser automations with runTask

Workflows

Create and run multi-step automations

Browser Automation

Control cloud browsers with Playwright + AI

Error Handling

Handle errors and configure retries