Skip to main content
A task is a single browser automation. You describe what you want in natural language — Skyvern opens a browser, navigates to the URL, and executes the instructions with AI. For when to use tasks vs workflows, see Run a Task.

​
runTask

Start a browser automation. Skyvern opens a cloud browser, navigates to the URL, and executes your prompt with AI. 
const result = await skyvern.runTask({
  body: {
    prompt: "Get the title of the top post",
    url: "https://news.ycombinator.com",
  },
  waitForCompletion: true,
});
console.log(result.output);

​
Parameters

The runTask method accepts a single request object with the following shape:
ParameterTypeRequiredDefaultDescription
body.promptstringYes—Natural language instructions for what the AI should do.
body.urlstringNoundefinedStarting page URL. If omitted, the AI navigates from a blank page.
body.engineRunEngineNo"skyvern_v2"AI engine. Options: "skyvern_v2", "skyvern_v1", "openai_cua", "anthropic_cua", "ui_tars".
body.max_stepsnumberNoundefinedCap the number of AI steps to limit cost. Run terminates with timed_out if hit.
body.data_extraction_schemaRecord<string, unknown> | stringNoundefinedJSON schema constraining the output shape.
body.proxy_locationProxyLocationNoundefinedRoute the browser through a geographic proxy.
body.browser_session_idstringNoundefinedRun inside an existing browser session.
body.publish_workflowbooleanNofalseSave the generated code as a reusable workflow. Only works with skyvern_v2.
body.webhook_urlstringNoundefinedURL to receive a POST when the run finishes.
body.error_code_mappingRecord<string, string>NoundefinedMap custom error codes to failure reasons.
body.totp_identifierstringNoundefinedIdentifier for TOTP verification.
body.totp_urlstringNoundefinedURL to receive TOTP codes.
body.titlestringNoundefinedDisplay name for this run in the dashboard.
body.modelRecord<string, unknown>NoundefinedOverride the output model definition.
body.user_agentstringNoundefinedCustom User-Agent header for the browser.
body.extra_http_headersRecord<string, string>NoundefinedAdditional HTTP headers injected into every browser request.
body.browser_addressstringNoundefinedConnect to a browser at this CDP address instead of spinning up a new one.
waitForCompletionbooleanNofalseBlock until the run finishes.
timeoutnumberNo1800Max wait time in seconds when waitForCompletion is true.

​
Returns TaskRunResponse

FieldTypeDescription
run_idstringUnique identifier. Starts with tsk_ for task runs.
statusstring"created", "queued", "running", "completed", "failed", "terminated", "timed_out", or "canceled".
outputRecord<string, unknown> | nullExtracted data from the run. Shape depends on your prompt or data_extraction_schema.
downloaded_filesFileInfo[] | undefinedFiles downloaded during the run.
recording_urlstring | undefinedURL to the session recording video.
screenshot_urlsstring[] | undefinedFinal screenshots (most recent first).
failure_reasonstring | undefinedError description if the run failed.
app_urlstring | undefinedLink to view this run in the Cloud UI.
step_countnumber | undefinedNumber of AI steps taken.
script_runScriptRunResponse | undefinedCode execution result if the run used generated code.
created_atstringWhen the run was created.
finished_atstring | undefinedWhen the run finished.

​
Examples

Extract structured data: 
const result = await skyvern.runTask({
  body: {
    prompt: "Extract the name, price, and rating of the top 3 products",
    url: "https://example.com/products",
    data_extraction_schema: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string" },
          price: { type: "string" },
          rating: { type: "number" },
        },
      },
    },
  },
  waitForCompletion: true,
});
console.log(result.output);
// [{ name: "Widget A", price: "$29.99", rating: 4.5 }, ...]
Run inside an existing browser session: 
const session = await skyvern.createBrowserSession({});

const result = await skyvern.runTask({
  body: {
    prompt: "Log in and download the latest invoice",
    url: "https://app.example.com/login",
    browser_session_id: session.browser_session_id,
  },
  waitForCompletion: true,
});
Limit cost with max_steps: 
const result = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form",
    url: "https://example.com/contact",
    max_steps: 10,
  },
  waitForCompletion: true,
});
Publish as a reusable workflow: 
const result = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form with the provided data",
    url: "https://example.com/contact",
    publish_workflow: true,
  },
  waitForCompletion: true,
});
// The generated workflow is saved and can be re-triggered via runWorkflow

​
getRun

Get the current status and results of any run (task or workflow). 
const run = await skyvern.getRun("tsk_v2_486305187432193504");
console.log(run.status, run.output);

​
Parameters

ParameterTypeRequiredDescription
runIdstringYesThe run ID returned by runTask or runWorkflow.

​
Returns GetRunResponse

A discriminated union based on run_type. All variants share the same core fields as TaskRunResponse above, plus a run_type field (task_v1, task_v2, openai_cua, anthropic_cua, ui_tars, workflow_run). Workflow run responses additionally include run_with and ai_fallback fields.

​
cancelRun

Cancel a running or queued run. 
await skyvern.cancelRun("tsk_v2_486305187432193504");

​
Parameters

ParameterTypeRequiredDescription
runIdstringYesThe run ID to cancel.
The run transitions to canceled status. If the run has already finished, this is a no-op.

​
getRunTimeline

Get the step-by-step timeline of a run. Each entry represents one AI action with screenshots and reasoning. 
const timeline = await skyvern.getRunTimeline("tsk_v2_486305187432193504");
for (const step of timeline) {
  console.log(`Step ${step.order}: ${step.type} — ${step.status}`);
}

​
Parameters

ParameterTypeRequiredDescription
runIdstringYesThe run ID.

​
Returns WorkflowRunTimeline[]

Each timeline entry contains step details including type, status, order, and associated artifacts.

​
getRunArtifacts

Get all artifacts (screenshots, recordings, generated code, etc.) for a run. 
const artifacts = await skyvern.getRunArtifacts("tsk_v2_486305187432193504");
for (const artifact of artifacts) {
  console.log(`${artifact.artifact_type}: ${artifact.uri}`);
}

​
Parameters

ParameterTypeRequiredDescription
runIdstringYesThe run ID.
artifactTypeArtifactType | ArtifactType[]NoFilter by artifact type.

​
Returns Artifact[]

​
getArtifact

Get a single artifact by ID. 
const artifact = await skyvern.getArtifact("art_486305187432193504");
console.log(artifact.uri);

​
Parameters

ParameterTypeRequiredDescription
artifactIdstringYesThe artifact ID.

​
Returns Artifact

​
retryRunWebhook

Re-send the webhook notification for a completed run. Useful if your webhook endpoint was down when the run finished. 
await skyvern.retryRunWebhook("tsk_v2_486305187432193504");

​
Parameters

ParameterTypeRequiredDescription
runIdstringYesThe run ID.

​
Polling pattern

If you don’t use waitForCompletion, poll getRun manually: 
const task = await skyvern.runTask({
  body: {
    prompt: "Extract product data",
    url: "https://example.com/products",
  },
});

const terminalStatuses = ["completed", "failed", "terminated", "timed_out", "canceled"];
let run;
while (true) {
  run = await skyvern.getRun(task.run_id);
  if (terminalStatuses.includes(run.status)) break;
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

console.log(run.output);
For production, prefer waitForCompletion: true or webhooks over manual polling.