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.
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:
Argument | Description |
---|---|
|
The slug indicating the task to run, available from your task's page in the Render Dashboard: Every task slug has the following format: For example: |
|
A list containing the task's input arguments. Each element maps to the task's corresponding positional argument. The 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:
Property | Description |
---|---|
|
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:
|
|
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
-
From your workflow's Tasks page in the Render Dashboard, click a task to open its Runs page.
-
Click Run Task in the top-right corner of the page:
A dialog appears for providing the task's input arguments:
-
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.
-
Click Start task.
Your new task run appears at the top of the Runs table.
Running manually with the Render CLI
-
Make sure your development machine has version 2.4.2 or later of the Render CLI:
If it doesn't, install the latest version.
-
Run the following command:
The CLI opens an interactive menu of all workflow tasks in your workspace:
-
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:
-
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.
-
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:
-
Select a run and press Enter, then select the
results
command.The CLI opens a view of the run's results: