Running Workflow Tasks

Execute registered tasks from your application code.

Render Workflows are in limited early access.

During the early access period, the Workflows API and Python SDK might introduce breaking changes.

Request Early Access

After you create a workflow and register tasks, you can start triggering task runs from your applications (such as other Render services).

You can also manually trigger runs in the Render Dashboard and CLI to help with testing and debugging.

First: Create an API key

Triggering task runs from your code requires a Render API key.

Create an API key with these steps, then return here.

Running with the Workflows SDK

The Workflows SDK is currently available only for Python.

SDKs for other languages are coming soon. To execute tasks from other languages, use the Render API.

Follow these steps to execute workflow tasks from application code using the Workflows SDK.

1. Install the SDK

Make sure to add render_sdk to your application's requirements.txt file (or equivalent).

2. Set your API key

In your application's environment, set the RENDER_API_KEY environment variable to your API key:

The SDK client automatically detects and uses the value of this environment variable.

Alternatively, you can provide your API key explicitly when initializing the client.

3. Initialize the client and trigger a run

The following code demonstrates initializing the SDK client, triggering a task run, and waiting for the run to complete. See below for more details.

You trigger a task run by calling the client's workflows.run_task method. This method takes the following arguments:

ArgumentDescription

task_identifier

The slug indicating the task to run, available from your task's page in the Render Dashboard:

Task slug in the Render Dashboard

Every task slug has the following format:

For example: my-workflow/calculate-square

input_data

A list containing the task's input arguments. Each element maps to the task's corresponding positional argument.

The calculate-square task in the example above takes a single integer argument.

For tasks that take zero arguments, provide an empty list, [].

The workflows.run_task method returns an AwaitableTaskRun object as soon as the run is created. This object provides the run's id and initial status, which are both available immediately. You can await this object to wait for the run to complete, at which point all other properties are available.

For full options and details, see the Python SDK reference.

Running with the Render API

The Render API provides an endpoint for triggering task runs, along with a variety of endpoints for retrieving workflow and task run details. The Workflows SDK uses the Render API behind the scenes, and you can also use it directly from your own code.

Start a task run by sending a POST request to the Run a Task endpoint. The JSON body for this request includes two properties:

PropertyDescription
task

Required. An identifier specifying the task to run.

You can provide either of two identifiers, both of which are available from your task's page in the Render Dashboard:

Task slug in the Render Dashboard

  • The task's slug
    • This has the format {workflow-slug}/{task-name} (for example, my-workflow/calculate-square)
  • The task's ID
    • This has the format tsk-abc123...
input

Required. A list containing values for the task's input arguments.

For a task that takes zero arguments, provide an empty list, [].

Running manually

You can manually trigger task runs directly from the Render Dashboard and CLI. This is handy for testing and debugging new tasks.

Running tasks manually in the Render Dashboard

  1. From your workflow's Tasks page in the Render Dashboard, click a task to open its Runs page.

  2. Click Run Task in the top-right corner of the page:

    Running a task in the Render Dashboard

    A dialog appears for providing the task's input arguments:

    Providing input arguments for a task run in the Render Dashboard

  3. Provide the task's input arguments as a JSON array. Each array element maps to the task's corresponding positional argument.

    For example, you can provide [5] for a task that takes a single integer argument, or [] for a task that takes zero arguments.

    You can click Format and Validate to cleanly structure your input and confirm that it's valid JSON.

  4. Click Start task.

    Your new task run appears at the top of the Runs table.

Running manually with the Render CLI

  1. Make sure your development machine has version 2.4.2 or later of the Render CLI:

    If it doesn't, install the latest version.

  2. Run the following command:

    The CLI opens an interactive menu of all workflow tasks in your workspace:

    Listing tasks in the Render CLI

  3. Select a task and press Enter, then select the run command.

    The CLI prompts you to provide the task's input arguments as a JSON array:

    Providing input arguments for a task run in the Render CLI

  4. Provide your desired arguments (or [] for a task that takes zero arguments) and press Enter. The CLI kicks off your task with a request to the Render API and begins tailing its logs.

    You can remain in this view to view live logs from your task run.

  5. Press Esc to navigate back up to the list of commands for your task. This time select the runs command.

    The CLI opens an interactive menu of the task's runs:

    Viewing task runs in the Render CLI

  6. Select a run and press Enter, then select the results command.

    The CLI opens a view of the run's results:

    Viewing task run details in the Render CLI