Runs represent a specific execution instance of a Task. When you want Vern to perform an action defined by a Task, you create a Run.

​
Purpose of Runs

  • Task Execution: Trigger the actual performance of a defined Task.
  • Input Provision: Provide the specific data (inputs) required by the Task for this particular execution.
  • Tracking: Each Run represents a traceable instance of a workflow execution, allowing you to monitor its status and results.

​
Creating Runs

Runs can be created via the Vern SDK or REST API, as they typically correspond to real-time events or user actions in your application.

​
Using the SDK

import Vern from "vern";

// Initialize the SDK
const vern = Vern({ apiKey: "YOUR_API_KEY" });

// Use the explicit runs.create method
const run = await vern.runs.create({
  taskId: "getCarDetails",
  inputs: { registration: "YLG19A" },
});

​
Using the REST API

curl -X POST https://vern.so/api/v1/runs \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "getCarDetails",
    "inputs": {
      // Input data required by the Task
      "registration": "YLG19A"
    }
  }'

Key Components:

  • taskId: Required. Specifies which Task definition to execute.
  • inputs: An object containing the data required by the specified Task. The structure must match the inputs defined when the Task was created in the UI.

​
Run ID and Asynchronous Execution

Upon successful submission of a Run creation request, the API immediately returns a response containing a unique Run ID (e.g., run_mno123pqr456).

Important: Vern executes tasks asynchronously. The immediate API response only confirms that the run request was received and queued. It does not mean the task has completed.

The Run ID is used to:

  • Check the status of the run (e.g., queued, running, completed, failed).
  • Retrieve the results or output of the run once it has completed.

​
Polling for Run Completion

You can poll for run completion using our SDK:

async function pollRunUntilComplete(runId, interval = 10000) {
  while (true) {
    const runDetails = await vern.runs.retrieve(runId);
    if (runDetails.status === "completed") {
      return runDetails;
    }
    await new Promise((resolve) => setTimeout(resolve, interval));
  }
}

const completedRun = await pollRunUntilComplete(run.id);
// completedRun.result will have the result when done

​
Example: Running “Find Property Details”

Using the property search example:

  • We provide the taskId for “Find Property Details”.
  • We provide the inputs (like address and include_photos) for the property search.

Vern receives this, queues the job, and executes the browser-based task to search for and extract the property details.

​
Next Steps

Understanding Runs completes the core workflow: Define browser actions (Tasks) and execute them (Runs). Explore the API reference for details on managing and monitoring runs.