Runs

Execute Tasks with specific inputs.

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. Each run requires a Task ID and can optionally include specific inputs.

Using the SDK

Here are examples of using the Vern SDK in different programming languages:

Typescript

import Vern from "vern";

const client = new Vern({
  apiKey: process.env['VERN_SDK_API_KEY'], // This is the default and can be omitted
});

async function main() {
  const run = await client.runs.create({ taskId: 'enterInventoryItem' });
  console.log(run.id);
}

main();

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": "enterInventoryItem",
    "inputs": {
      // Optional task-specific inputs
    }
  }'

Request Components:

• taskId (required): The ID of the task to execute
• inputs (optional): Object containing task-specific input data
• profileId (optional): User-specified UID for a profile linked via magic link
• url (optional): A URL to be processed by the task

Response Status Codes:

Common run status codes:

• 200: Task run created successfully
• 400: Invalid request parameters
• 401: Invalid or missing API key
• 429: Rate limit exceeded
• 500: Internal server error

Run Lifecycle and Status

A run goes through the following states during its lifecycle:

• queued: Initial state when the run is created
• running: The task is actively being executed
• complete: Task execution finished successfully
• failed: Task execution encountered an error

The current state can be retrieved through the API or SDK using the run’s ID.

Retrieving Run Status

You can check the status of a run using the SDK or REST API:

Here are examples of retrieving run status using the SDK in different programming languages:

JavaScript

const run = await client.runs.retrieve('run_id');
console.log(run.status);

The response includes:

• id: Unique identifier for the run
• task: Name of the executed task
• inputs: The provided input data
• status: Current run status
• created_at: When the run was created
• started_at: When execution began
• completed_at: When execution finished
• response: Task execution results (when completed)

Next Steps

Now that you understand Runs, explore the Tasks documentation to learn how to define the actions that your runs will execute. You can also learn about Webhooks to receive notifications when runs complete.