Workflows SDK for Python

Usage and symbol reference

Render Workflows is in limited early access.

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

Request Early Access

The Render SDK for Python provides support for:

Defining workflow tasks
Triggering runs of those tasks from your other Python code

When triggering runs, you use different classes for asynchronous and synchronous execution contexts.

Install

shell

$ pip install render_sdk

Make sure to add render_sdk as a dependency to your application's requirements.txt, pyproject.toml, or equivalent.

Defining tasks

The following symbols pertain to creating and registering tasks in your workflow service. For guidance on how to use them, see Defining Workflow Tasks.

The `Workflows` class

Handles defining and registering workflow tasks. Initialize this in each file where you define tasks.

Initializing

`Workflows(default_retry, default_timeout, default_plan)`

Initializes a new Workflows object. All arguments are optional.

python

from render_sdk import Workflows, Retry

# Basic initialization
app = Workflows()

# Initialization with all options set
app = Workflows(
  default_retry=Retry(
    max_retries=3,
    wait_duration_ms=1000,
    backoff_scaling=1.5
  ),
  default_timeout=300,
  default_plan="standard"
)

Argument Description

Argument	Description
`default_retry`	A `Retry` object defining default retry behavior for all tasks in this workflow. Individual tasks can override this.
`default_timeout`	The default timeout (in seconds) for all tasks in this workflow. Individual tasks can override this.
`default_plan`	The default instance type to use for all tasks in this workflow. Individual task definitions can override this. The following instance types are available for all workspaces: `starter` (0.5 CPU / 512 MB RAM) `standard` (1 CPU / 2 GB RAM) `pro` (2 CPU / 4 GB RAM) You can request access to the following additional instance types for your workspace: `pro_plus` (4 CPU / 8 GB RAM) `pro_max` (8 CPU / 16 GB RAM) `pro_ultra` (16 CPU / 32 GB RAM)

`default_retry`

A Retry object defining default retry behavior for all tasks in this workflow.

Individual tasks can override this.

`default_timeout`

The default timeout (in seconds) for all tasks in this workflow.

Individual tasks can override this.

`default_plan`

The default instance type to use for all tasks in this workflow.

Individual task definitions can override this.

The following instance types are available for all workspaces:

starter (0.5 CPU / 512 MB RAM)
standard (1 CPU / 2 GB RAM)
pro (2 CPU / 4 GB RAM)

You can request access to the following additional instance types for your workspace:

pro_plus (4 CPU / 8 GB RAM)
pro_max (8 CPU / 16 GB RAM)
pro_ultra (16 CPU / 32 GB RAM)

`Workflows.from_workflows(*apps, default_retry, default_timeout, default_plan)`

Initializes a new Workflows object that incorporates tasks from one or more other Workflows objects.

Use this in your workflow's entry point file if you import task definitions from other files:

python

from render_sdk import Workflows
from math_tasks import app as math_app
from text_tasks import app as text_app

app = Workflows.from_workflows(math_app, text_app)

if __name__ == "__main__":
  app.start()

If you set any defaults with this method (such as default_timeout), those defaults apply only to tasks registered directly on this object (not to tasks registered on the imported objects).

Argument	Description
`*apps`	Required. One or more `Workflows` objects to incorporate into this object. If two objects define a task with the same name, this raises a `ValueError`.
`default_retry`	Default retry configuration for new tasks registered on the combined object. Same as the `Workflows` constructor argument.
`default_timeout`	Default timeout for new tasks registered on the combined object. Same as the `Workflows` constructor argument.
`default_plan`	Default instance type for new tasks registered on the combined object. Same as the `Workflows` constructor argument.

The `@app.task` decorator

You apply the @app.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 import Workflows 

app = Workflows() 

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

Example with all arguments

python

from render_sdk import Workflows, Retry

app = Workflows()

@app.task(
  name="calc_square", # Give the task a custom name (defaults to function name)
  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
    backoff_scaling=1.5 # Increase delay by 50% after each retry (exponential backoff)
  ),
  timeout_seconds=300, # Timeout in seconds
  plan="standard" # Resource plan
)
def calculate_square(a: int) -> int:
  return a * a

Argument reference

Option	Description
Task decorator 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.
`retry`	A `Retry` object defining retry behavior for the task. See retry arguments below.
`timeout_seconds`	The timeout for the task's runs, in seconds. Must be between 30 seconds (`30`) and 24 hours (`86400`), inclusive. The default value is 2 hours.
`plan`	The default instance type to use for the task's runs. Supported values: `starter` (0.5 CPU / 512 MB RAM) `standard` (1 CPU / 2 GB RAM) `pro` (2 CPU / 4 GB RAM) You can request access to the following additional instance types for your workspace: `pro_plus` (4 CPU / 8 GB RAM) `pro_max` (8 CPU / 16 GB RAM) `pro_ultra` (16 CPU / 32 GB RAM) The default value is `standard`.
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.
`backoff_scaling`	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. If you provide a `Retry` object but omit this field, the default value is `1.5`. If you omit the `Retry` object entirely, the default value is `2`.

The `app.start()` method

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

main.py

python

from render_sdk import Workflows

app = Workflows()

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

if __name__ == "__main__":
  app.start()

This method takes no arguments.

Triggering runs (async)

Use the RenderAsync class to trigger and manage task runs from any asynchronous execution context (such as a FastAPI route handler). All methods are async and return awaitable objects.

The `RenderAsync` class

Constructor

`RenderAsync(token)`

Initializes a new RenderAsync object. All arguments are optional.

python

from render_sdk import RenderAsync

# Basic initialization
render = RenderAsync()

# Initialization with API key
render = RenderAsync(
  token="rnd_abc123…"
)

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.

`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.

Task methods (async)

These methods are available on the workflows attribute of the RenderAsync class.

`async` `workflows.start_task(task_identifier, input_data)`

Kicks off a run of the registered task with the specified identifier, passing the specified arguments.

To instead run a task and wait for it to complete, use workflows.run_task.

On success: Returns an AwaitableTaskRun object representing the initial state of the task run. You can await this object to wait for the run to complete.

Raises: ClientError, ServerError, TimeoutError

python

# Execute the calculate_square task with an input of 2
started_task_run = await render.workflows.start_task(
  "my-workflow/calculate_square",
  [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(finished_task_run.results) # Prints the task run's result, in this case [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 or dictionary containing the task's input arguments.: If you provide a list, elements are positional based on the task's function signature. If you provide a dictionary, each key maps to a parameter name in the task's function signature. 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 or dictionary containing the task's input arguments.:

If you provide a list, elements are positional based on the task's function signature.
If you provide a dictionary, each key maps to a parameter name in the task's function signature.

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

`async` `workflows.run_task(task_identifier, input_data)`

Starts the registered task with the specified identifier, waits for it to complete, and returns the result.

To instead kick off a run without waiting for it to complete, use workflows.start_task.

On success: Returns a TaskRunDetails object for the completed task run.

Raises: ClientError, ServerError, TimeoutError, TaskRunError

python

# Run the calculate_square task and wait for the result
task_run = await render.workflows.run_task(
  "my-workflow/calculate_square",
  [2]
)
print(task_run.results) # [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 or dictionary containing the task's input arguments.: If you provide a list, elements are positional based on the task's function signature. If you provide a dictionary, each key maps to a parameter name in the task's function signature. 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 or dictionary containing the task's input arguments.:

If you provide a list, elements are positional based on the task's function signature.
If you provide a dictionary, each key maps to a parameter name in the task's function signature.

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

`async` `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
  owner_id=["tea-d3jm7ai4d50c73fale60"] # Limit to these workspace IDs
)

await render.workflows.list_task_runs(params)

Supported fields of the ListTaskRunsParams object include:

Parameter	Description
`limit`	Optional integer specifying the maximum number of task runs to return.
`cursor`	Optional cursor string for pagination. Use this to retrieve the next page of results.
`owner_id`	Optional list of workspace IDs to filter results by. Only task runs from these workspaces will be returned.

`async` `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 render.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...

`async` `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 render.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...

`async` `workflows.task_run_events(task_run_ids)`

Streams completion events for one or more task runs via Server-Sent Events (SSE). Returns an async iterator that yields a TaskRunDetails object each time a specified task run completes or fails.

The connection stays open until all events are received or you break out of the loop.

Raises: ClientError, ServerError, TimeoutError

python

# Start multiple tasks
run1 = await render.workflows.start_task("my-workflow/add", [1, 2])
run2 = await render.workflows.start_task("my-workflow/add", [5, 8])

# Stream events until all runs complete
pending = {run1.id, run2.id}
async for event in render.workflows.task_run_events(list(pending)):
  print(f"Run {event.id}: status={event.status}")
  pending.discard(event.id)
  if not pending:
    break

Argument Description

Argument	Description
`task_run_ids`	Required. A list of task run IDs to stream events for. Each ID has the format `trn-abc123...`

`task_run_ids`

Required. A list of task run IDs to stream events for.

Each ID has the format trn-abc123...

The `AwaitableTaskRun` class

Represents the initial state of a task run as returned by the async workflows.start_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 render.workflows.start_task(
  "my-workflow/calculate_square",
  [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.

Triggering runs (sync)

Use the Render class in any synchronous execution context (such as a default Flask or Django app). All methods are blocking.

The `Render` class

Constructor

`Render(token)`

Initializes a new Render object. All arguments are optional.

python

from render_sdk import Render

# Basic initialization
render = Render()

# Initialization with API key
render = Render(
  token="rnd_abc123…"
)

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.

`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.

Task methods (sync)

These methods are available on the workflows attribute of the Render class.

`workflows.start_task(task_identifier, input_data)`

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

To instead run a task and wait for it to complete, use workflows.run_task.

On success: Returns a TaskRun object representing the initial state of the task run (e.g. id, status). To wait for completion, poll workflows.get_task_run or use workflows.run_task.

Raises: ClientError, ServerError, TimeoutError

python

started_task_run = render.workflows.start_task(
  "my-workflow/calculate_square",
  [2]
)
# Poll with get_task_run(started_task_run.id) or use run_task() to block until done

Argument	Description
`task_identifier`	Required. The slug indicating the task to run. Format: `{workflow-slug}/{task-name}` (e.g. `my-workflow/calculate_square`).
`input_data`	Required. A list or dictionary containing the task's input arguments. For zero arguments, use `[]`.

`workflows.run_task(task_identifier, input_data)`

Starts the task, waits for it to complete, and returns the result.

To instead kick off a run without waiting for it to complete, use workflows.start_task.

On success: Returns a TaskRunDetails object.

Raises: ClientError, ServerError, TimeoutError, TaskRunError

python

task_run = render.workflows.run_task("my-workflow/calculate_square", [2])
print(task_run.results)

Argument	Description
`task_identifier`	Required. The slug indicating the task to run. Format: `{workflow-slug}/{task-name}`.
`input_data`	Required. A list or dictionary containing the task's input arguments. For zero arguments, use `[]`.

`workflows.list_task_runs(params)`

Lists task runs that match optional filters.

On success: Returns a list of TaskRun objects.

Raises: ClientError, ServerError, TimeoutError

python

from render_sdk.client.types import ListTaskRunsParams
params = ListTaskRunsParams(limit=10, cursor="…", owner_id=["tea-…"])
render.workflows.list_task_runs(params)

Supported fields: limit, cursor, owner_id. See workflows.list_task_runs for parameter descriptions.

`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

render.workflows.get_task_run("trn-abc123")

Argument	Description
`task_run_id`	Required. The ID of the task run (format `trn-abc123...`).

`workflows.cancel_task_run(task_run_id)`

Cancels the task run. Raises ClientError if not found or not running.

On success: Returns None.

Raises: ClientError, ServerError, TimeoutError

python

render.workflows.cancel_task_run("trn-abc123")

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

`workflows.task_run_events(task_run_ids)`

Streams completion events via SSE. Returns a synchronous iterator that yields a TaskRunDetails object each time a specified task run completes or fails.

Raises: ClientError, ServerError, TimeoutError

python

for event in render.workflows.task_run_events(["trn-abc123"]):
  print(f"Run {event.id}: status={event.status}")

Argument	Description
`task_run_ids`	Required. List of task run IDs (format `trn-abc123...`).

Additional types

The `TaskRun` class

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

From the sync workflows.start_task method
Calling the workflows.list_task_runs method (sync or async)

To get a run's full details including results, call workflows.get_task_run (sync or async) and provide the run's ID to obtain a TaskRunDetails object.

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...`
`status`	The initial status of the task run. This is usually `pending`.
`parent_task_run_id`	The ID of this run's parent run, if this run was chained. For a root-level run, this value is the root run's ID or empty.
`root_task_run_id`	The ID of the root task run in this run's execution chain. For a root-level run, this value matches `id`.
`retries`	The number of times the task run has retried so far. For a newly started run, this is typically `0`.
`attempts`	A list of `TaskAttempt` objects representing each execution attempt so far (including retries).
`started_at`	The datetime when the task run started executing. Not present if `status` is `pending`.
`completed_at`	The datetime when the task run finished (successfully or otherwise). Present only if status is one of `completed`, `failed`, or `canceled`.

The `TaskRunDetails` class

Provides the full details of a task run. Obtained in one of the following ways:

awaiting an AwaitableTaskRun object returned by the async workflows.start_task method:

python

started_task_run = await render.workflows.start_task(
  "my-workflow/calculate_square",
  [2]
)
finished_task_run = await started_task_run

Calling the workflows.run_task method of the Render or RenderAsync class:

python

task_run_details = await render.workflows.run_task("my-workflow/calculate_square", [2])

Calling the workflows.get_task_run method of the Render or RenderAsync class:
python
```
task_run_details = await render.workflows.get_task_run("trn-abc123")
```
Iterating over events from the workflows.task_run_events method of the Render or RenderAsync class:
python
```
async for event in render.workflows.task_run_events(["trn-abc123"]):
  task_run_details = event
```

Properties

A TaskRunDetails object includes all of the same properties as a TaskRun object, plus:

Property	Description
`results`	A list containing the task's return value(s). This value is always an empty list if `status` is not `completed`.
`input_`	The argument values that were passed to the task run, in the same format they were provided (as a list or a dictionary). Note the trailing underscore (`_`) in this property name.
`error`	The error message if the task run failed. Present only if `status` is `failed`.
`attempts`	A list of `TaskAttemptDetails` objects (more detailed than the `TaskAttempt` list on `TaskRun`) representing each individual execution attempt for this run, including 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,
    RateLimitError,
    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)
`RateLimitError`	A subclass of `ClientError`. Raised when a request to the Render API returns a 429 (rate limit exceeded) error code.
`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 a task run fails (e.g. when `await`ing an `AwaitableTaskRun` or when calling `workflows.run_task` or sync `workflows.run_task`).

Install

Defining tasks

The Workflows class

Initializing

Workflows(default_retry, default_timeout, default_plan)

default_retry

default_timeout

default_plan

Workflows.from_workflows(*apps, default_retry, default_timeout, default_plan)

*apps

default_retry

default_timeout

default_plan

The @app.task decorator

Minimal example

Example with all arguments

Argument reference

name

retry

timeout_seconds

plan

max_retries

wait_duration_ms

backoff_scaling

The app.start() method

Triggering runs (async)

The RenderAsync class

Constructor

RenderAsync(token)

token

Task methods (async)

async workflows.start_task(task_identifier, input_data)

task_identifier

input_data

async workflows.run_task(task_identifier, input_data)

task_identifier

input_data

async workflows.list_task_runs(params)

limit

cursor

owner_id

async workflows.get_task_run(task_run_id)

task_run_id

async workflows.cancel_task_run(task_run_id)

task_run_id

async workflows.task_run_events(task_run_ids)

task_run_ids

The AwaitableTaskRun class

Properties

id

status

Triggering runs (sync)

The Render class

Constructor

Render(token)

token

Task methods (sync)

workflows.start_task(task_identifier, input_data)

task_identifier

input_data

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

workflows.task_run_events(task_run_ids)

task_run_ids

Additional types

The TaskRun class

Properties

id

task_id

status

parent_task_run_id

root_task_run_id

retries

attempts

The `Workflows` class

`Workflows(default_retry, default_timeout, default_plan)`

`default_retry`

`default_timeout`

`default_plan`

`Workflows.from_workflows(*apps, default_retry, default_timeout, default_plan)`

`*apps`

`default_retry`

`default_timeout`

`default_plan`

The `@app.task` decorator

`name`

`retry`

`timeout_seconds`

`plan`

`max_retries`

`wait_duration_ms`

`backoff_scaling`

The `app.start()` method

The `RenderAsync` class

`RenderAsync(token)`

`token`

`async` `workflows.start_task(task_identifier, input_data)`

`task_identifier`

`input_data`

`async` `workflows.run_task(task_identifier, input_data)`

`task_identifier`

`input_data`

`async` `workflows.list_task_runs(params)`

`limit`

`cursor`

`owner_id`

`async` `workflows.get_task_run(task_run_id)`

`task_run_id`

`async` `workflows.cancel_task_run(task_run_id)`

`task_run_id`

`async` `workflows.task_run_events(task_run_ids)`

`task_run_ids`

The `AwaitableTaskRun` class

`id`

`status`

The `Render` class

`Render(token)`

`token`

`workflows.start_task(task_identifier, input_data)`

`task_identifier`

`input_data`

`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`

`workflows.task_run_events(task_run_ids)`

`task_run_ids`

The `TaskRun` class

`id`

`task_id`

`status`

`parent_task_run_id`

`root_task_run_id`

`retries`

`attempts`

`started_at`

`completed_at`

The `TaskRunDetails` class

`results`

`input_`

`error`

`attempts`

`RenderError`

`ClientError`

`RateLimitError`

`ServerError`

`TimeoutError`

`TaskRunError`