Skip to main content
A workflow chains multiple steps (blocks) into a single automation. Workflows support loops, conditionals, data passing between steps, and code-based re-execution. For conceptual background, see Build a Workflow.

​
runWorkflow

Execute a workflow by its permanent ID. Skyvern opens a cloud browser and runs each block in sequence. 
const result = await skyvern.runWorkflow({
  body: {
    workflow_id: "wpid_abc123",
  },
  waitForCompletion: true,
});
console.log(result.output);

​
Parameters

ParameterTypeRequiredDefaultDescription
body.workflow_idstringYes—The workflow’s permanent ID (wpid_...).
body.parametersRecord<string, unknown>NoundefinedInput parameters defined in the workflow. Keys must match parameter names.
body.browser_session_idstringNoundefinedRun inside an existing browser session.
body.browser_profile_idstringNoundefinedLoad a browser profile (cookies, storage) into the session.
body.proxy_locationProxyLocationNoundefinedRoute the browser through a geographic proxy.
body.webhook_urlstringNoundefinedURL to receive a POST when the run finishes.
body.titlestringNoundefinedDisplay name for this run in the dashboard.
body.totp_identifierstringNoundefinedIdentifier for TOTP verification.
body.totp_urlstringNoundefinedURL to receive TOTP codes.
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.
templatebooleanNoundefinedRun a template workflow.
waitForCompletionbooleanNofalseBlock until the workflow finishes.
timeoutnumberNo1800Max wait time in seconds when waitForCompletion is true.

​
Returns WorkflowRunResponse

FieldTypeDescription
run_idstringUnique identifier. Starts with wr_ for workflow runs.
statusstring"created", "queued", "running", "completed", "failed", "terminated", "timed_out", or "canceled".
outputRecord<string, unknown> | nullExtracted data from the workflow’s output block.
downloaded_filesFileInfo[] | undefinedFiles downloaded during the run.
recording_urlstring | undefinedURL to the session recording.
failure_reasonstring | undefinedError description if the run failed.
app_urlstring | undefinedLink to view this run in the Cloud UI.
step_countnumber | undefinedTotal AI steps taken across all blocks.
run_withstring | undefinedWhether the run used "code" or "agent".
ai_fallbackboolean | undefinedWhether AI fallback was configured.
script_runScriptRunResponse | undefinedCode execution result. Contains ai_fallback_triggered if code was used.

​
Examples

Pass parameters to a workflow: 
const result = await skyvern.runWorkflow({
  body: {
    workflow_id: "wpid_invoice_extraction",
    parameters: {
      company_name: "Acme Corp",
      date_range: "2025-01-01 to 2025-12-31",
    },
  },
  waitForCompletion: true,
});
Run with a browser profile (skip login): 
const result = await skyvern.runWorkflow({
  body: {
    workflow_id: "wpid_daily_report",
    browser_profile_id: "bpf_abc123",
  },
  waitForCompletion: true,
});

​
createWorkflow

Create a new workflow from a JSON or YAML definition. 
const workflow = await skyvern.createWorkflow({
  body: {
    json_definition: {
      title: "Extract Products",
      workflow_definition: {
        parameters: [
          {
            key: "target_url",
            parameter_type: "workflow",
            workflow_parameter_type: "string",
            description: "URL to scrape",
          },
        ],
        blocks: [
          {
            block_type: "task",
            label: "extract",
            prompt: "Extract the top 3 products with name and price",
            url: "{{ target_url }}",
          },
        ],
      },
    },
  },
});
console.log(workflow.workflow_permanent_id);

​
Parameters

ParameterTypeRequiredDescription
body.json_definitionobjectNoWorkflow definition as a JSON object.
body.yaml_definitionstringNoWorkflow definition as a YAML string.
folder_idstringNoFolder to organize the workflow in.
You must provide either body.json_definition or body.yaml_definition.

​
Returns Workflow

FieldTypeDescription
workflow_idstringUnique ID for this version.
workflow_permanent_idstringStable ID across all versions. Use this to run workflows.
versionnumberVersion number.
titlestringWorkflow title.
workflow_definitionWorkflowDefinitionThe full definition including blocks and parameters.
statusstring | undefinedWorkflow status.
created_atstringWhen the workflow was created.

​
getWorkflows

List all workflows. Supports filtering and pagination. 
const workflows = await skyvern.getWorkflows({});
for (const wf of workflows) {
  console.log(`${wf.title} (${wf.workflow_permanent_id})`);
}

​
Parameters

ParameterTypeRequiredDefaultDescription
pagenumberNoundefinedPage number for pagination.
page_sizenumberNoundefinedNumber of results per page.
only_saved_tasksbooleanNoundefinedOnly return saved tasks.
only_workflowsbooleanNoundefinedOnly return workflows (not saved tasks).
only_templatesbooleanNoundefinedOnly return templates.
titlestringNoundefinedFilter by exact title.
search_keystringNoundefinedSearch by title.
folder_idstringNoundefinedFilter by folder.
statusWorkflowStatus | WorkflowStatus[]NoundefinedFilter by status.

​
Returns Workflow[]

​
getWorkflow

Get a specific workflow by its permanent ID. 
const workflow = await skyvern.getWorkflow("wpid_abc123");
console.log(workflow.title, `v${workflow.version}`);

​
Parameters

ParameterTypeRequiredDescription
workflowPermanentIdstringYesThe workflow’s permanent ID.
versionnumberNoSpecific version to retrieve. Defaults to latest.
templatebooleanNoWhether to fetch a template workflow.

​
Returns Workflow

​
getWorkflowVersions

List all versions of a workflow. 
const versions = await skyvern.getWorkflowVersions("wpid_abc123");
for (const v of versions) {
  console.log(`v${v.version} — ${v.modified_at}`);
}

​
Parameters

ParameterTypeRequiredDescription
workflowPermanentIdstringYesThe workflow’s permanent ID.
templatebooleanNoWhether to fetch template versions.

​
Returns Workflow[]

​
updateWorkflow

Update an existing workflow’s definition. 
const updated = await skyvern.updateWorkflow("wpid_abc123", {
  json_definition: {
    title: "Extract Products Updated",
    workflow_definition: {
      blocks: [
        {
          block_type: "task",
          label: "extract_data",
          prompt: "Extract the top 5 products",
          url: "https://example.com/products",
        },
      ],
      parameters: [],
    },
  },
});
console.log(`Updated to v${updated.version}`);

​
Parameters

ParameterTypeRequiredDescription
workflowIdstringYesThe workflow’s permanent ID (wpid_...).
json_definitionobjectNoUpdated workflow definition as JSON.
yaml_definitionstringNoUpdated workflow definition as YAML.

​
Returns Workflow

Creates a new version of the workflow.

​
deleteWorkflow

Delete a workflow. 
await skyvern.deleteWorkflow("wf_abc123");

​
Parameters

ParameterTypeRequiredDescription
workflowIdstringYesThe workflow version ID to delete.