Workflows SDK for Python

Symbol reference

Render Workflows are in limited early access.

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

Render provides a Python SDK that supports both registering workflow tasks and executing those tasks from application code.

Install

shell

$ pip install render_sdk

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

The `@task` decorator

You apply the @task decorator to a Python function to register it as a workflow task. For details, see Defining Workflow Tasks

Minimal example

python

from render_sdk.workflows import task 

@task 
def calculate_square(a: int) -> int:
  return a * a

Example with all arguments

python

from render_sdk.workflows.task import task, Options, Retry

@task(
  name="calc_square", # Give the task a custom name (defaults to function name)
  options=Options(
    retry=Retry( # Define default retry logic for the task
      max_retries=3, # Retry up to 3 times (i.e., 4 total attempts)
      wait_duration_ms=1000, # Set a base retry delay of 1 second
      factor=1.5 # Increase delay by 50% after each retry (exponential backoff)
  )
)
def calculate_square(a: int) -> int:
  return a * a

Argument reference

Option	Description
Top-level arguments
`name`	A custom name for the task. This affects the task's slug, which you use to reference the task when running it. If omitted, defaults to the name of the decorated function.
`options`	Contains all other arguments for the task definition. Currently supports a single argument: `retry`.
Retry arguments
`max_retries`	The maximum number of retries to attempt for a given run of the task. The total number of attempts is up to `max_retries + 1` (the initial attempt plus all retries).
`wait_duration_ms`	The base delay before attempting the first retry, in milliseconds.
`factor`	The exponential backoff factor. After each retry, the previous delay is multiplied by this factor. For example, a factor of `1.5` increases the delay by 50% after each retry.

The `start` function

The start function serves as the entry point for your workflow during both task registration and task execution. Your workflow definition must call this function as part of startup:

python

from render_sdk.workflows import task, start

@task
def calculate_square(a: int) -> int:
  return a * a

if __name__ == "__main__":
  start()

This function takes no arguments.

The `Client` class

The render_sdk.client.Client class provides methods for running registered tasks from Python applications (such as a Render web service or cron job):

python

from render_sdk.client import Client

client = Client()
await client.workflows.run_task("calculate_square", {"a": 2})

Constructor

`Client(token, base_url)`

Initializes a new Client instance. All arguments are optional.

python

from render_sdk.client import Client

# Basic initialization
client = Client()

# Initialization with all arguments
client = Client(
  token="rnd_abc123…", # API key
  base_url="localhost:8120" # Local task server URL
)

Argument Description

Argument	Description
`token`	The API key to use for authentication. If omitted, the client automatically detects and uses the value of the `RENDER_API_KEY` environment variable.
`base_url`	The base URL to use for task-related requests. Specify only for local development. If omitted: By default, the client uses the base URL of the Render API (`https://api.render.com`). If the `RENDER_LOCAL_DEV_URL` environment variable is set, the client uses the value of this variable. If the `RENDER_USE_LOCAL_DEV` environment variable is set to `true`, the client uses the local task server's default URL (`http://localhost:8120`).

`token`

The API key to use for authentication.

If omitted, the client automatically detects and uses the value of the RENDER_API_KEY environment variable.

`base_url`

The base URL to use for task-related requests. Specify only for local development.

If omitted:

By default, the client uses the base URL of the Render API (https://api.render.com).
If the RENDER_LOCAL_DEV_URL environment variable is set, the client uses the value of this variable.
If the RENDER_USE_LOCAL_DEV environment variable is set to true, the client uses the local task server's default URL (http://localhost:8120).

If you don't provide an API key, the client will automatically detect and use the value of the RENDER_API_KEY environment variable (if set).

Task methods

All methods below are async.

`workflows.run_task(task_identifier, input_data)`

Runs the registered task with the specified identifier, passing the specified arguments.

On success: Returns an AwaitableTaskRun object representing the initial state of the task run.

Raises: ClientError, ServerError, TimeoutError

python

# Execute the calculate_square task with an input of 2
started_task_run = await client.workflows.run_task("calculate_square", {"x": 2})

task_run_id = started_task_run.id # ID is available immediately
task_run_status = started_task_run.status # Initial status is available immediately

finished_task_run = await started_task_run # Other properties become available after the task run completes
print(task_run.result) # Prints the task run's result (4)

Argument Description

Argument	Description
`task_identifier`	Required. The slug indicating the task to run, available from your task's page in the Render Dashboard: Always has the format `{workflow-slug}/{task-name}` (e.g., `my-workflow/calculate-square`).
`input_data`	Required. A list containing values for the task's input arguments. For a task that takes zero arguments, provide an empty list, `[]`.

`task_identifier`

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

Task slug in the Render Dashboard

Always has the format {workflow-slug}/{task-name} (e.g., my-workflow/calculate-square).

`input_data`

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

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

`workflows.list_task_runs(params)`

Lists task runs that match optional filters specified in the provided ListTaskRunsParams object.

On success: Returns a list of TaskRun objects.

Raises: ClientError, ServerError, TimeoutError

python

from render_sdk.client.types import ListTaskRunsParams

params = ListTaskRunsParams(
  limit=10, # Return up to 10 runs
  cursor="cfQ74cE2sDI=", # Start from this cursor
  owners=["tea-d3jm7ai4d50c73fale60"] # Limit to these workspaces
)

await client.workflows.list_task_runs(params)

`workflows.get_task_run(task_run_id)`

Retrieves the details of the task run with the specified ID.

On success: Returns a TaskRunDetails object.

Raises: ClientError, ServerError, TimeoutError

python

await client.workflows.get_task_run("trn-abc123")

Argument Description

Argument	Description
`task_run_id`	Required. The ID of the task run to retrieve. Has the format `trn-abc123...`

`task_run_id`

Required. The ID of the task run to retrieve.

Has the format trn-abc123...

`workflows.cancel_task_run(task_run_id)`

Cancels the task run with the specified ID. This raises a ClientError if the task run is not found, or if it isn't currently running.

On success: Returns None.

Raises: ClientError, ServerError, TimeoutError

python

await client.workflows.cancel_task_run("trn-abc123")

Argument Description

Argument	Description
`task_run_id`	Required. The ID of the task run to cancel. Has the format `trn-abc123...`

`task_run_id`

Required. The ID of the task run to cancel.

Has the format trn-abc123...

The `AwaitableTaskRun` class

Represents the initial state of a task run as returned by the workflows.run_task method.

You can await this object to wait for the task run to complete. On success, it returns a TaskRunDetails object:

python

started_task_run = await client.workflows.run_task("calculate_square", {"x": 2})
finished_task_run = await started_task_run

If the task run fails, this await raises a TaskRunError exception.

Properties

Property Description

`id`

The ID of the task run.

Has the format trn-abc123...

`status`

The initial status of the task run. This is usually pending.

The `TaskRunDetails` class

Represents the current state of a task run. Obtained in one of the following ways:

awaiting an AwaitableTaskRun object returned by workflows.run_task:

python

started_task_run = await client.workflows.run_task("calculate_square", {"x": 2})
finished_task_run = await started_task_run

Calling the workflows.get_task_run method:

python

task_run_details = await client.workflows.get_task_run("trn-abc123")

Properties

Property	Description
`id`	The ID of the task run. Has the format `trn-abc123...`
`task_id`	The ID of the run's associated task. Has the format `tsk-abc123...`.
`input_`	A list containing the argument values that were passed to the task run. Note the trailing underscore (`_`) in this property name.
`status`	The current status of the task run. One of the following: `pending` `running` `completed` `failed` `canceled`
`results`	The task's return value. Present only if `status` is `completed`.
`parent_task_run_id`	The ID of the parent task run, if this task was called as a subtask by another task. For a root-level task, this value is `None`.
`root_task_run_id`	The ID of the root task run in this run's execution chain. For a root-level task, this value matches the value of `id`.
`retries`	The number of times the task run has retried. For runs that succeed without retries, this value is `0`. Learn more about retries.

Exception types

Exceptions raised by the SDK have one of the types listed below. RenderError is the parent class for all other exception types.

python

from render_sdk.client.errors import (
    RenderError, # Parent class for other exceptions
    ClientError,
    ServerError,
    TimeoutError,
    TaskRunError
)

Exception	Description
`RenderError`	The base class for all exceptions raised by the SDK.
`ClientError`	Raised when a request to the Render API returns a 400-level error code. Common causes include: Invalid API key Invalid task identifier Invalid task arguments Invalid action (e.g., canceling a task run that is already completed)
`ServerError`	Raised when a request to the Render API returns a 500-level error code.
`TimeoutError`	Raised when a request to the Render API times out.
`TaskRunError`	Raised when an `await`ed task run fails.

Install

The @task decorator

Minimal example

Example with all arguments

Argument reference

name

options

max_retries

wait_duration_ms

factor

The start function

The Client class

Constructor

Client(token, base_url)

token

base_url

Task methods

workflows.run_task(task_identifier, input_data)

task_identifier

input_data

workflows.list_task_runs(params)

workflows.get_task_run(task_run_id)

task_run_id

workflows.cancel_task_run(task_run_id)

task_run_id

The AwaitableTaskRun class

Properties

id

status

The TaskRunDetails class

Properties

id

task_id

input_

status

results

parent_task_run_id

root_task_run_id

retries

Exception types

RenderError

ClientError

ServerError

TimeoutError

TaskRunError

Workflows SDK for Python

The `@task` decorator

`name`

`options`

`max_retries`

`wait_duration_ms`

`factor`

The `start` function

The `Client` class

`Client(token, base_url)`

`token`

`base_url`

`workflows.run_task(task_identifier, input_data)`

`task_identifier`

`input_data`

`workflows.list_task_runs(params)`

`workflows.get_task_run(task_run_id)`

`task_run_id`

`workflows.cancel_task_run(task_run_id)`

`task_run_id`

The `AwaitableTaskRun` class

`id`

`status`

The `TaskRunDetails` class

`id`

`task_id`

`input_`

`status`

`results`

`parent_task_run_id`

`root_task_run_id`

`retries`

`RenderError`

`ClientError`

`ServerError`

`TimeoutError`

`TaskRunError`