Render Workflows

https://render.com/docs/workflows
Admin
Render Workflows is an end-to-end orchestration and execution engine for long-running, distributed...
Tokens:20,652
Snippets:255
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize Client and Trigger Task Run in TypeScript

Source: https://render.com/docs/workflows-running

Example of initializing the Render client, starting a task, and awaiting completion.

```typescript
import { Render } from '@renderinc/sdk'

async function triggerTaskRun() {
  // Initialize the client
  const render = new Render()

  // Kick off a task run
  const startedRun = await render.workflows.startTask(
    'my-workflow/calculate_square',
    [2]
  )

  console.log('Task run started:', startedRun.taskRunId)

  // Wait for run to complete
  const finishedRun = await startedRun.get()

  console.log('Task run completed:', finishedRun.id)
  console.log('Final status:', finishedRun.status)
}

triggerTaskRun()
```

--------------------------------

### Install the SDK

Source: https://render.com/docs/workflows-sdk-typescript

Commands to install the Render SDK for TypeScript via npm.

```shell
$ npm install @renderinc/sdk
```

```shell
$ npm install @renderinc/sdk@latest
```

--------------------------------

### Install Render SDK for Python

Source: https://render.com/docs/workflows-running

Commands to install or upgrade the Render SDK in a Python project.

```shell
pip install render
```

```shell
pip install --upgrade render
```

--------------------------------

### app.start()

Source: https://render.com/docs/workflows-sdk-python

Initializes the workflow application. This method must be called to start task registration and run execution.

```APIDOC
## app.start()

### Description
Starts the workflow application. This is the entry point for your workflow during task registration and run execution.

### Parameters
None
```

--------------------------------

### Start the local task server

Source: https://render.com/docs/workflows-local-development

Initiate the local task server by providing the command used to start your workflow service.

```shell
render workflows dev -- <WORKFLOW_START_COMMAND>
```

```shell
render workflows dev -- npm start
```

```shell
render workflows dev -- python main.py
```

--------------------------------

### Install Render CLI via Homebrew

Source: https://render.com/docs/workflows-tutorial

Use Homebrew to install or update the Render CLI on macOS or Linux.

```shell
brew update
brew install render
```

--------------------------------

### Install Render CLI via cURL

Source: https://render.com/docs/workflows-tutorial

Use the provided shell script to install the Render CLI on Linux or macOS.

```shell
curl -fsSL https://raw.githubusercontent.com/render-oss/cli/refs/heads/main/bin/install.sh | sh
```

--------------------------------

### Set build commands for workflow templates

Source: https://render.com/docs/workflows-tutorial

Use these commands to install dependencies for the Hello World template during the build process.

```bash
npm install
```

```bash
pip install -r requirements.txt
```

--------------------------------

### Set start commands for workflow templates

Source: https://render.com/docs/workflows-tutorial

Use these commands to execute the workflow application after the build process completes.

```bash
npm start
```

```bash
python main.py
```

--------------------------------

### Interact with local tasks via CLI

Source: https://render.com/docs/workflows-local-development

Commands for listing, starting, and viewing task runs locally using the Render CLI.

```shell
render workflows tasks list --local
```

```shell
render workflows tasks list -o text --local
NAME               ID                          CREATED                      
calculateSquare    tsk-d6kba95mo5j36bpg8rs0    2026-03-04T14:41:40-08:00    
sumSquares         tsk-d6kba95mo5j36bpg8rsg    2026-03-04T14:41:40-08:00    
flipCoin           tsk-d6kba95mo5j36bpg8rt0    2026-03-04T14:41:40-08:00
```

```shell
render workflows tasks start calculateSquare -o text --input='[3]' --local
Created task run trn-d6kchpdmo5j36bpg8rvg for calculateSquare
```

```shell
render workflows runs list calculateSquare -o text --local
ID                          STATUS       STARTED                      COMPLETED                    DURATION     
trn-d6kchpdmo5j36bpg8rvg    completed    2026-03-04T16:05:57-08:00    2026-03-04T16:05:57-08:00    364.577ms
```

```shell
render workflows runs show calculateSquare -o text --local
Task run details for trn-d6kchpdmo5j36bpg8rvg: status completed, started at 2026-03-04 16:05:57.371701 -0800 PST, completed at 2026-03-04 16:05:57.736278 -0800 PST,
input: [3],
results: [9]
```

--------------------------------

### render.workflows.run_task(task_slug, input_data)

Source: https://render.com/docs/workflows-sdk-python

Starts a task and waits for it to complete before returning the result.

```APIDOC
## render.workflows.run_task(task_slug, input_data)

### Description
Starts a registered task, waits for completion, and returns a TaskRunDetails object.

### Parameters
- **task_slug** (string) - Required - The identifier for the task in the format {workflow-slug}/{task-name}.
- **input_data** (list or dict) - Required - The input arguments for the task function.
```

--------------------------------

### workflows.startTask

Source: https://render.com/docs/workflows-sdk-typescript

Starts a task and returns a result object that can be used to wait for completion.

```APIDOC
## workflows.startTask(taskSlug, args)

### Description
Initiates a task run and returns a `TaskRunResult` object. Call `.get()` on the result to retrieve the `TaskRunDetails`.

### Usage
```typescript
const startedRun = await render.workflows.startTask('my-workflow/calculateSquare', [2])
const taskRunDetails = await startedRun.get() 
```
```

--------------------------------

### Check Render CLI version

Source: https://render.com/docs/workflows-local-development

Verify the installed version of the Render CLI to ensure it meets the minimum requirement of 2.12.0.

```shell
render --version
```

--------------------------------

### Start the local task server on a custom port

Source: https://render.com/docs/workflows-local-development

Override the default port 8120 by specifying a custom port using the --port flag.

```shell
render workflows dev --port 8121 -- python main.py
```

--------------------------------

### Define a Workflow Task

Source: https://render.com/docs/workflows-tutorial

Minimal task definition examples for TypeScript and Python.

```typescript
import { task, type TaskContext } from '@renderinc/sdk/workflows'

// Minimal task definition
const calculateSquare = task(
  { name: 'calculateSquare' },
  function calculateSquare(ctx: TaskContext, a: number): number {
    return a * a
  }
)
```

```python
from render import TaskContext, Workflows

app = Workflows()

# Minimal task definition
@app.task
def calculate_square(ctx: TaskContext, a: int) -> int:
  return a * a

if __name__ == "__main__":
  app.start() # Workflow entry point
```

--------------------------------

### render.workflows.runTask(taskSlug, inputData, signal)

Source: https://render.com/docs/workflows-sdk-typescript

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

```APIDOC
## render.workflows.runTask(taskSlug, inputData, signal)

### Description
Starts the registered task with the specified identifier, waits for it to complete, and returns the result as a TaskRunDetails object.

### Parameters
- **taskSlug** (string) - Required - The slug indicating the task to run (format: {workflow-slug}/{task-name}).
- **inputData** (array) - Required - An array containing the task's input arguments.
- **signal** (AbortSignal) - Optional - An optional AbortSignal used to cancel the request.
```

--------------------------------

### Start a workflow task in Python

Source: https://render.com/docs/workflows-sdk-python

Initiates a task without waiting for completion. Use the returned ID to poll for status updates.

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

--------------------------------

### Run a workflow task synchronously in Python

Source: https://render.com/docs/workflows-sdk-python

Starts a task and blocks execution until it completes, returning the final result.

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

--------------------------------

### Initialize a Starter Project

Source: https://render.com/docs/workflows-tutorial

Generate a new project directory with a starter task definition.

```shell
render workflows init
```

--------------------------------

### Build Render CLI from Source

Source: https://render.com/docs/workflows-tutorial

Clone the repository and build the CLI binary using Go.

```shell
git clone git@github.com:render-oss/cli.git
cd cli
go build -o render
```

--------------------------------

### Initialize Workflow Application

Source: https://render.com/docs/workflows-sdk-python

The app.start() method is the required entry point for workflow task registration and execution.

```python
from render import TaskContext, Workflows

app = Workflows()

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

if __name__ == "__main__":
  app.start() # highlight-line
```

--------------------------------

### Commit Initial Project Files

Source: https://render.com/docs/workflows-tutorial

Navigate to the project directory and commit the generated files to Git.

```shell
cd workflows-demo
git add .
git commit -m "Initial commit"
```

--------------------------------

### Initialize Workflows Object

Source: https://render.com/docs/workflows-sdk-python

Demonstrates basic and advanced initialization of the Workflows class with optional retry, timeout, and plan configurations.

```python
from render 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="flex"
)
```

--------------------------------

### Initialize the Render client

Source: https://render.com/docs/workflows-sdk-python

Instantiate the Render class with or without an explicit API token. If no token is provided, the client defaults to the RENDER_API_KEY environment variable.

```python
from render import Render

# Basic initialization
render = Render()

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

--------------------------------

### Trigger a task run asynchronously

Source: https://render.com/docs/workflows-sdk-typescript

Starts a task and retrieves the result later using the returned TaskRunResult object.

```typescript

// Trigger a run of calculateSquare with an input of 2
const startedRun = await render.workflows.startTask(
  'my-workflow/calculateSquare',
  [2]
)


const taskRunId: string = startedRun.taskRunId // Available immediately


const finishedRun = await startedRun.get()
console.log(finishedRun.results)
```

--------------------------------

### render.workflows.start_task(task_slug, input_data)

Source: https://render.com/docs/workflows-sdk-python

Kicks off a task run asynchronously without waiting for completion.

```APIDOC
## render.workflows.start_task(task_slug, input_data)

### Description
Starts a registered task and returns an AwaitableTaskRun object immediately.

### Parameters
- **task_slug** (string) - Required - The identifier for the task in the format {workflow-slug}/{task-name}.
- **input_data** (list or dict) - Required - The input arguments for the task function.
```

--------------------------------

### Render(options)

Source: https://render.com/docs/workflows-sdk-typescript

Initializes a new Render SDK client instance for authentication and API interaction.

```APIDOC
## Render(options)

### Description
Initializes a Render SDK client. If the token is omitted, the client automatically detects and uses the value of the RENDER_API_KEY environment variable.

### Parameters
- **options** (object) - Optional - Configuration object containing the API token.
  - **token** (string) - Optional - The API key to use for authentication.
```

--------------------------------

### render.workflows.startTask(taskSlug, inputData, signal)

Source: https://render.com/docs/workflows-sdk-typescript

Kicks off a run of a registered task and returns a TaskRunResult object.

```APIDOC
## render.workflows.startTask(taskSlug, inputData, signal)

### Description
Kicks off a run of the registered task with the specified identifier, passing the specified arguments. Returns a TaskRunResult object representing the started run.

### Parameters
- **taskSlug** (string) - Required - The slug indicating the task to run (format: {workflow-slug}/{task-name}).
- **inputData** (array) - Required - An array containing the task's input arguments.
- **signal** (AbortSignal) - Optional - An optional AbortSignal used to cancel the request.
```

--------------------------------

### Render(token=None)

Source: https://render.com/docs/workflows-sdk-python

Initializes a new Render client instance. The client can be configured with an explicit API token or will automatically detect the RENDER_API_KEY environment variable.

```APIDOC
## Render(token=None)

### Description
Initializes a new `Render` object for use in synchronous execution contexts. All methods are blocking unless otherwise specified.

### Parameters
- **token** (string) - Optional - The API key to use for authentication. If omitted, the client attempts to use the `RENDER_API_KEY` environment variable.

### Usage Example
```python
from render import Render

# Basic initialization
render = Render()

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

--------------------------------

### Configure Render SDK for local development

Source: https://render.com/docs/workflows-local-development

Set environment variables to redirect task triggers to a local task server.

```bash
# Always set this:
RENDER_USE_LOCAL_DEV=true

# Also set this if you're using a non-default URL/port:
# RENDER_LOCAL_DEV_URL=http://localhost:8121
```

--------------------------------

### Initialize Project in Non-Interactive Mode

Source: https://render.com/docs/workflows-tutorial

Use flags to bypass prompts when initializing a project in automated environments.

```shell
render workflows init --confirm --language py --template hello-world --dir my-workflow --install-deps --git
```

--------------------------------

### Initialize RenderAsync Client

Source: https://render.com/docs/workflows-sdk-python

Use RenderAsync for asynchronous task management. Authentication can be handled via the RENDER_API_KEY environment variable or by passing a token directly.

```python
from render import RenderAsync

# Basic initialization
render = RenderAsync()

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

--------------------------------

### Initialize the Render SDK client

Source: https://render.com/docs/workflows-sdk-typescript

Initializes the Render client using either the default environment variable or a provided API token.

```typescript

import { Render } from '@renderinc/sdk'


// Basic initialization (uses RENDER_API_KEY from env)
const render = new Render()


// Initialization with API key
const renderWithToken = new Render({
  token: 'rnd_abc123...'
})
```

--------------------------------

### Workflows.__init__

Source: https://render.com/docs/workflows-sdk-python

Initializes a new Workflows object to handle task definition and registration.

```APIDOC
## Workflows.__init__(*, default_retry=None, default_timeout=None, default_plan=None)

### Description
Initializes a new Workflows object. All arguments are optional.

### Parameters
- **default_retry** (Retry) - Optional - A Retry object defining default retry behavior for all tasks in this workflow.
- **default_timeout** (int) - Optional - The default timeout (in seconds) for all tasks in this workflow.
- **default_plan** (str) - Optional - The default compute plan to use for all tasks in this workflow (e.g., 'flex', '2c-4g').
```

--------------------------------

### List Workflow Tasks via CLI

Source: https://render.com/docs/workflows-running

Display an interactive menu of all available workflow tasks within the current workspace.

```shell
render workflows tasks list
```

--------------------------------

### Visualize Background Job Workflow

Source: https://render.com/docs/workflows

Timeline representation of an employee onboarding background job involving user provisioning, payroll, accounts, and benefits.

```timeline
onboard_employee() (start +0s, run 40s, end +40s) [root]
├── provision_user() (start +1s, run 19s, end +20s)
├── add_to_payroll() (start +22s, run 17s, end +39s)
├── create_accounts() (start +22s, run 15s, end +37s)
└── enroll_benefits() (start +22s, run 13s, end +35s)
```

--------------------------------

### Set Render API Key Environment Variable

Source: https://render.com/docs/workflows-running

Export the API key to the environment for automatic SDK detection.

```bash
export RENDER_API_KEY=rnd_abc123…
```

--------------------------------

### Register Python tasks

Source: https://render.com/docs/workflows-defining

Combine multiple Workflows apps using Workflows.from_workflows in the main entry point.

```python
from render 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) # highlight-line

if __name__ == "__main__":
  app.start() # SDK entry point
```

--------------------------------

### Run a task

Source: https://render.com/docs/workflows-sdk-python

Execute a task and retrieve its details directly using run_task.

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

--------------------------------

### Serial Task Execution in Python

Source: https://render.com/docs/workflows-defining

Demonstrates the performance impact of awaiting tasks sequentially instead of in parallel.

```python
@app.task
async def sum_squares_slower(ctx: TaskContext, a: int, b: int) -> int:
  # ⚠️ Not parallel!
  result1 = await ctx.run(calculate_square, a)
  result2 = await ctx.run(calculate_square, b) # Executes after first run completes
  return result1 + result2

@app.task
def calculate_square(ctx: TaskContext, a: int) -> int:
  return a * a
```

--------------------------------

### TaskContext.run(task, ...args)

Source: https://render.com/docs/workflows-sdk-typescript

Chains a run of a registered task on a separate instance.

```APIDOC
## TaskContext.run(task, ...args)

### Description
Chains a run of the specified task. This method is available on the `TaskContext` object provided to every task function.

### Parameters
- **task** (function) - Required - The `task()`-registered function to run.
- **...args** (any) - Optional - Arguments to pass to the task function.

### Returns
- **Promise** - Resolves with the chained run's return value.

### Example
```typescript
const sumSquares = task(
  { name: 'sumSquares' },
  async (ctx: TaskContext, a: number, b: number): Promise<number> => {
    const [first, second] = await Promise.all([
      ctx.run(calculateSquare, a), 
      ctx.run(calculateSquare, b) 
    ])
    return first + second
  }
)
```

--------------------------------

### Execute Tasks Asynchronously

Source: https://render.com/docs/workflows-sdk-python

Use start_task to trigger a run and receive an AwaitableTaskRun object, or run_task to wait for completion and return results directly.

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

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

--------------------------------

### workflows.start_task

Source: https://render.com/docs/workflows-running

Triggers a task run by its identifier and provides input arguments. Returns an object containing the task run ID and status.

```APIDOC
## workflows.start_task

### Description
Triggers a task run for a specified task identifier. The method accepts input arguments as a list or dictionary and returns a task run object.

### Parameters
- **task_identifier** (string) - Required - The slug of the task to run, formatted as {workflow-slug}/{task-name}.
- **input_data** (list or dict) - Required - The input arguments for the task. Use a list for positional arguments or a dictionary for named parameters.

### Returns
- **AwaitableTaskRun** (object) - In async contexts, this object can be awaited to retrieve full task run details upon completion.
- **TaskRun** (object) - In sync contexts, this object provides immediate access to the task run ID and status.
```

--------------------------------

### Visualize AI Agent Workflow

Source: https://render.com/docs/workflows

Timeline representation of an AI agent workflow showing context gathering, skill execution, and response composition.

```timeline
run_agent() (start +0s, run 30s, end +30s) [root]
├── gather_context() (start +1s, run 9s, end +10s)
│   ├── search_web() (start +2s, run 8s, end +10s)
│   └── fetch_docs() (start +2s, run 7s, end +9s)
├── execute_skills() (start +11s, run 8s, end +19s)
└── compose_response() (start +20s, run 9s, end +29s)
```

--------------------------------

### Defining Task Configuration

Source: https://render.com/docs/workflows-defining

Configuring task compute plans, timeouts, and retry logic using the SDK.

```APIDOC
## Task Configuration

### Description
Configure task execution behavior including compute resources, timeouts, and retry policies.

### Parameters
- **name** (string) - Required - The unique name of the task.
- **plan** (string) - Optional - The compute plan ID (e.g., '2c-4g', '2c-8g', '4c-8g', '4c-16g'). Defaults to 'flex'.
- **timeoutSeconds** (number) - Optional - Task timeout in seconds (30s to 24h). Defaults to 2 hours.
- **retry** (object) - Optional - Retry configuration object.
  - **maxRetries** (number) - Number of retries.
  - **waitDurationMs** (number) - Base delay in milliseconds.
  - **backoffScaling** (number) - Multiplier for backoff delay.

### TypeScript Example
```typescript
const myTask = task(
  {
    name: 'myTask',
    plan: '2c-4g',
    timeoutSeconds: 86400,
    retry: {
      maxRetries: 3,
      waitDurationMs: 1000,
      backoffScaling: 1.5
    }
  },
  function myTask(ctx: TaskContext, a: number): number {
    return a * a
  }
)
```

### Python Example
```python
@app.task(
  plan="2c-4g",
  timeout_seconds=86400,
  retry=Retry(
    max_retries=3,
    wait_duration_ms=1000,
    backoff_scaling=1.5
  )
)
def my_task(ctx: TaskContext, a: int) -> int:
  return a * a
```
```

--------------------------------

### Triggering Workflow Tasks via SDK and API

Source: https://render.com/docs/workflows

Initiate task runs using the Render SDK or direct HTTP requests. Ensure proper authentication is configured for API access.

```typescript
import { Render } from '@renderinc/sdk'

const render = new Render()

// Trigger a run of calculateSquare with the argument `2`
const startedRun = await render.workflows.startTask(
  'my-workflow/calculateSquare',
  [2],
)
const finishedRun = await startedRun.get()
console.log(finishedRun.results)
```

```python
from render import RenderAsync

render = RenderAsync()

# Trigger a run of calculate_square with the argument `2`
started_run = await render.workflows.start_task(
  "my-workflow/calculate_square",
  [2],
)
finished_run = await started_run
print(finished_run.results)
```

```python
from render import Render

render = Render()

# Trigger a run of calculate_square with the argument `2`
finished_run = render.workflows.run_task(
  "my-workflow/calculate_square",
  [2],
)
print(finished_run.results)
```

```bash
# Trigger a run of calculate_square with the argument `2`
curl -X POST https://api.render.com/v1/task-runs \
  -H "Authorization: Bearer rnd_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"task": "my-workflow/calculate_square", "input": [2]}'
```

--------------------------------

### Triggering an Asynchronous Task Run

Source: https://render.com/docs/workflows-running

Use the RenderAsync client in asynchronous contexts to trigger a task and await its completion.

```python
from render import RenderAsync
import asyncio

async def trigger_task_run():

  # Initialize the async client
  render = RenderAsync()

  # Kick off a task run
  started_run = await render.workflows.start_task(
    "my-workflow/calculate_square",
    [2]
  )

  print(f"Task run started: {started_run.id}")
  print(f"Initial status: {started_run.status}")

  # Wait for run to complete
  finished_run = await started_run

  print(f"Task run completed: {finished_run.id}")
  print(f"Final status: {finished_run.status}")

if __name__ == "__main__":
  asyncio.run(trigger_task_run())
```

--------------------------------

### Import TypeScript tasks

Source: https://render.com/docs/workflows-defining

Register distributed tasks by importing their respective files in the main entry point.

```typescript
import './math-tasks'
import './text-tasks'
```

--------------------------------

### Aggregate Workflows from Multiple Files

Source: https://render.com/docs/workflows-sdk-python

Initializes a Workflows object by combining tasks from multiple imported Workflows instances.

```python
from render 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()
```

--------------------------------

### Triggering a Synchronous Task Run

Source: https://render.com/docs/workflows-running

Use the Render client in synchronous contexts to trigger a task and poll for its completion status.

```python
import time
from render import Render

def trigger_task_run():

  # Initialize the client
  render = Render()

  # Kick off a task run
  started_run = render.workflows.start_task(
    "my-workflow/calculate_square",
    [2]
  )

  print(f"Task run started: {started_run.id}")
  print(f"Initial status: {started_run.status}")

  # Wait for run to complete (poll until terminal status)
  finished_run = render.workflows.get_task_run(started_run.id)
  while finished_run.status.value not in ("completed", "failed", "canceled"):
    time.sleep(1)
    finished_run = render.workflows.get_task_run(started_run.id)

  print(f"Task run completed: {finished_run.id}")
  print(f"Final status: {finished_run.status}")

if __name__ == "__main__":
  trigger_task_run()
```

--------------------------------

### Pass named arguments to a task run

Source: https://render.com/docs/workflows-sdk-python

Pass input arguments to a task run as named arguments using ctx.run.

```python
ctx.run(sum_squares, a=2, b=3)
```

--------------------------------

### RenderAsync(token=None)

Source: https://render.com/docs/workflows-sdk-python

Constructor for the RenderAsync client used to trigger and manage task runs.

```APIDOC
## RenderAsync(token=None)

### Description
Initializes a new RenderAsync object for interacting with Render Workflows.

### Parameters
- **token** (string) - Optional - The API key for authentication. If omitted, the client uses the RENDER_API_KEY environment variable.
```

--------------------------------

### Visualize ETL Pipeline Workflow

Source: https://render.com/docs/workflows

Timeline representation of an ETL pipeline showing order extraction, enrichment, cleaning, and warehouse loading.

```timeline
run_etl_pipeline() (start +0s, run 120s, end +120s) [root]
├── extract_orders() (start +3s, run 60s, end +63s)
│   ├── enrich_orders() (start +20s, run 38s, end +58s)
│   └── clean_orders() (start +20s, run 36s, end +56s)
└── load_warehouse() (start +68s, run 50s, end +118s)
```

--------------------------------

### Serial Task Execution in TypeScript

Source: https://render.com/docs/workflows-defining

Demonstrates the performance impact of awaiting tasks sequentially instead of in parallel.

```typescript
const sumSquaresSlower = task(
  { name: 'sumSquaresSlower' },
  async function sumSquaresSlower(ctx: TaskContext, a: number, b: number): Promise<number> {
    // ⚠️ Not parallel!
    const result1 = await ctx.run(calculateSquare, a)
    const result2 = await ctx.run(calculateSquare, b) // Executes after first run completes
    return result1 + result2
  }
)

const calculateSquare = task(
  { name: 'calculateSquare' },
  function calculateSquare(ctx: TaskContext, a: number): number {
    return a * a
  }
)
```

--------------------------------

### Pass positional arguments to a task run

Source: https://render.com/docs/workflows-sdk-python

Pass input arguments to a task run as positional arguments using ctx.run.

```python
ctx.run(sum_squares, 2, 3)
```

--------------------------------

### Chain task runs in Python

Source: https://render.com/docs/workflows-defining

Use ctx.run with asyncio.gather to execute chained tasks in parallel.

```python
from render import TaskContext, Workflows
import asyncio

app = Workflows()

# A task that chains two parallel runs
@app.task
async def sum_squares(ctx: TaskContext, a: int, b: int) -> int: # Must be async to await chained runs
  result1, result2 = await asyncio.gather(
    ctx.run(calculate_square, a),
    ctx.run(calculate_square, b)
  )
  return result1 + result2

@app.task
def calculate_square(ctx: TaskContext, a: int) -> int:
  return a * a
```

--------------------------------

### TaskContext.run()

Source: https://render.com/docs/workflows-sdk-python

The run method on the TaskContext object allows for chaining tasks, executing them on separate instances.

```APIDOC
## async TaskContext.run(task, *args, **kwargs)

### Description
Chains a run of the specified task on a separate instance.

### Parameters
- **task** (callable) - Required - The @app.task-decorated function to run.
- **args** (tuple) - Optional - Positional arguments for the task.
- **kwargs** (dict) - Optional - Named arguments for the task.

### Returns
- Returns the chained run's return value on success.

### Raises
- TaskRunError
- ValueError
```

--------------------------------

### task(options, func)

Source: https://render.com/docs/workflows-sdk-typescript

Registers a function as a workflow task with specified configuration options.

```APIDOC
## task(options, func)

### Description
Registers a provided function as a workflow task. Returns a task definition that can be used for run chaining.

### Parameters
- **options** (object) - Required - Configuration details for the task. Must include `name` (string). Optional fields include `retry` (object), `timeoutSeconds` (number), and `plan` (string).
- **func** (function) - Required - The function to register as a task. Must accept `TaskContext` as the first argument.

### Example
```typescript
import { task, type TaskContext } from '@renderinc/sdk/workflows'

const calculateSquare = task(
  {
    name: 'calculateSquare',
    retry: { maxRetries: 3, waitDurationMs: 1000, backoffScaling: 1.5 },
    timeoutSeconds: 300,
    plan: 'flex'
  },
  function calculateSquare(ctx: TaskContext, a: number): number {
    return a * a
  }
)
```

--------------------------------

### Import Render SDK Exceptions

Source: https://render.com/docs/workflows-sdk-python

Import the base RenderError class and specific subclasses to handle API and task execution errors.

```python
from render.client.errors import (
    RenderError, # Parent class for other exceptions
    ClientError,
    RateLimitError,
    ServerError,
    TimeoutError,
    TaskRunError
)
```

--------------------------------

### Configure task arguments and retry logic

Source: https://render.com/docs/workflows-sdk-python

Use the @app.task decorator with arguments to customize task naming, retry behavior, timeouts, and compute plans.

```python
from render import Retry, TaskContext, Workflows

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="2c-4g" # Compute plan
)
def calculate_square(ctx: TaskContext, a: int) -> int:
  return a * a
```

--------------------------------

### workflows.runTask

Source: https://render.com/docs/workflows-sdk-typescript

Executes a task and returns the full details of the run.

```APIDOC
## workflows.runTask(taskSlug, args)

### Description
Executes a task by its slug and returns a `TaskRunDetails` object containing the result.

### Usage
```typescript
const taskRunDetails = await render.workflows.runTask('my-workflow/calculateSquare', [2])
```
```

--------------------------------

### Await a task run

Source: https://render.com/docs/workflows-sdk-python

Obtain full task run details by awaiting an AwaitableTaskRun object.

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

--------------------------------

### Configure task compute plan

Source: https://render.com/docs/workflows-defining

Specify the compute resources for a task by setting the plan option in the task definition.

```typescript
const myTask = task(
  {
    name: 'myTask',
    plan: '2c-4g' // highlight-line
  },
  function myTask(ctx: TaskContext, a: number): number {
    return a * a
  }
)
```

```python
@app.task(
  plan="2c-4g" # highlight-line
)
def my_task(ctx: TaskContext, a: int) -> int:
  return a * a
```

--------------------------------

### Retrieve task run details with Python SDK

Source: https://render.com/docs/workflows-sdk-python

Fetches details for a specific task run using its ID.

```python
await render.workflows.get_task_run("trn-abc123")
```

--------------------------------

### render.workflows.listTaskRuns(params)

Source: https://render.com/docs/workflows-sdk-typescript

Lists task runs that match optional filters.

```APIDOC
## render.workflows.listTaskRuns(params)

### Description
Lists task runs that match optional filters and returns an array of TaskRunWithCursor objects.

### Parameters
- **params** (object) - Optional - Filter parameters for listing task runs (e.g., limit, ownerId).
```

--------------------------------

### Import SDK Error Types

Source: https://render.com/docs/workflows-sdk-typescript

Importing the base and specific error classes provided by the SDK.

```typescript
import {
  RenderError, // Parent class for other errors besides AbortError
  ClientError,
  ServerError,
  AbortError
} from '@renderinc/sdk'
```

--------------------------------

### Visualize Batch Processing Workflow

Source: https://render.com/docs/workflows

Timeline representation of a batch processing workflow showing concurrent item processing followed by aggregation.

```timeline
process_batch() (start +0s, run 120s, end +120s) [root]
├── process_item(…) (start +3s, run 82s, end +85s)
├── process_item(n) (start +3s, run 80s, end +83s)
├── process_item(1) (start +3s, run 78s, end +81s)
└── aggregate() (start +88s, run 30s, end +118s)
```

--------------------------------

### Await task run completion with Python SDK

Source: https://render.com/docs/workflows-sdk-python

Waits for a task run to complete and returns its details, or raises TaskRunError on failure.

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

--------------------------------

### List task runs in Python

Source: https://render.com/docs/workflows-sdk-python

Retrieves a list of task runs filtered by optional parameters like limit, cursor, or owner ID.

```python
from render.client.types import ListTaskRunsParams
params = ListTaskRunsParams(limit=10, cursor="…", owner_id=["tea-…"])
task_runs = render.workflows.list_task_runs(params)
for item in task_runs:
  print(item.task_run.id, item.cursor)
```

--------------------------------

### Trigger a task run via Render API

Source: https://render.com/docs/workflows-running

Use a POST request to the Run task endpoint to initiate a workflow task. The JSON body requires the task identifier and an input array or object.

```json
{
  "task": "my-workflow/calculate_square",
  "input": [2]
}
```

--------------------------------

### render.workflows.list_task_runs

Source: https://render.com/docs/workflows-sdk-python

Lists task runs that match optional filters.

```APIDOC
## render.workflows.list_task_runs(params=None)

### Description
Retrieves a list of task runs based on provided filters.

### Parameters
- **params** (ListTaskRunsParams) - Optional - Filtering parameters including limit, cursor, and owner_id.
```

--------------------------------

### Chain task runs with TaskContext.run

Source: https://render.com/docs/workflows-sdk-python

Use the ctx.run method within an async task function to trigger and await other workflow tasks.

```python
import asyncio

@app.task
async def sum_squares(ctx: TaskContext, a: int, b: int) -> int:
  first, second = await asyncio.gather(
    ctx.run(calculate_square, a), # highlight-line
    ctx.run(calculate_square, b) # highlight-line
  )
  return first + second
```

--------------------------------

### Task Identifier Format

Source: https://render.com/docs/workflows-running

The required format for specifying a task slug.

```text
{workflow-slug}/{task-name}
```

--------------------------------

### Workflows.from_workflows

Source: https://render.com/docs/workflows-sdk-python

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

```APIDOC
## Workflows.from_workflows(*apps, default_retry=None, default_timeout=None, default_plan=None)

### Description
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.

### Parameters
- **apps** (Workflows) - Required - One or more Workflows objects to incorporate into this object.
- **default_retry** (Retry) - Optional - The default retry configuration for new tasks registered on this workflow.
- **default_timeout** (int) - Optional - The default timeout for new tasks registered on this workflow.
- **default_plan** (str) - Optional - The default compute plan for new tasks registered on this workflow.
```

--------------------------------

### Configure Render API base URL

Source: https://render.com/docs/workflows-local-development

Use an environment variable to override the default Render API base URL for task-related endpoints.

```js
const TASKS_BASE_URL = process.env.RENDER_TASKS_URL || 'https://api.render.com'
```

--------------------------------

### async get_task_run(task_run_id)

Source: https://render.com/docs/workflows-sdk-python

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

```APIDOC
## async get_task_run(task_run_id)

### Description
Retrieves the details of the task run with the specified ID. Returns a `TaskRunDetails` object.

### Parameters
- **task_run_id** (str) - Required - The ID of the task run to retrieve (format: `trn-abc123...`).
```

--------------------------------

### Run a task and wait for completion

Source: https://render.com/docs/workflows-sdk-typescript

Executes a task and blocks until it finishes, returning the final task run details.

```typescript

const taskRun = await render.workflows.runTask(
  'my-workflow/calculateSquare',
  [2]
)


console.log(taskRun.status)
console.log(taskRun.results)
```

--------------------------------

### List task runs with Python SDK

Source: https://render.com/docs/workflows-sdk-python

Uses ListTaskRunsParams to filter task runs by limit, cursor, or owner ID.

```python
from render.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
)

task_runs = await render.workflows.list_task_runs(params)
for item in task_runs:
  print(item.task_run.id, item.cursor)
```

--------------------------------

### Iterate over task run events

Source: https://render.com/docs/workflows-sdk-python

Retrieve task run details by iterating over events from the task_run_events method.

```python
async for event in render.workflows.task_run_events(["trn-abc123"]):
  task_run_details = event
```

--------------------------------

### POST /v1/task-runs

Source: https://render.com/docs/workflows

Triggers a new task run for a specified workflow task.

```APIDOC
## POST /v1/task-runs

### Description
Triggers a run of a specific workflow task.

### Method
POST

### Endpoint
https://api.render.com/v1/task-runs

### Request Body
- **task** (string) - Required - The identifier of the workflow task to run.
- **input** (array) - Required - The arguments to pass to the task.

### Request Example
{
  "task": "my-workflow/calculate_square",
  "input": [2]
}
```

--------------------------------

### async list_task_runs(params=None)

Source: https://render.com/docs/workflows-sdk-python

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

```APIDOC
## async list_task_runs(params=None)

### Description
Lists task runs that match optional filters specified in the provided `ListTaskRunsParams` object. Returns a list of `TaskRunWithCursor` objects.

### Parameters
- **params** (ListTaskRunsParams) - Optional - Object containing filters: `limit` (int), `cursor` (str), `owner_id` (list of str).
```

--------------------------------

### Define Workflow Tasks

Source: https://render.com/docs/workflows-redirect

Define tasks using the Render SDK in TypeScript or Python. Tasks can be chained using the task context.

```typescript
import { task, type TaskContext } from '@renderinc/sdk/workflows'


// Basic task that takes one argument
const calculateSquare = task(
  { name: 'calculateSquare' },
  function calculateSquare(ctx: TaskContext, a: number): number {
    return a * a
  }
)


// Task that chains two parallel runs of calculateSquare
const sumSquares = task(
  { name: 'sumSquares' },
  async function sumSquares(ctx: TaskContext, a: number, b: number): Promise<number> {
  
    // Parallelize with Promise.all
    const [result1, result2] = await Promise.all([
      ctx.run(calculateSquare, a),
      ctx.run(calculateSquare, b)
    ])


    // Return the sum of the two results
    return result1 + result2
  }
)
```

```python
from render import TaskContext, Workflows
import asyncio


app = Workflows()


# Basic task that takes one argument
@app.task
def calculate_square(ctx: TaskContext, a: int) -> int:
  return a * a


# Task that chains two parallel runs of calculate_square
@app.task
async def sum_squares(ctx: TaskContext, a: int, b: int) -> int:


  # Parallelize with asyncio.gather
  result1, result2 = await asyncio.gather(
    ctx.run(calculate_square, a),
    ctx.run(calculate_square, b)
  )


  # Return the sum of the two results
  return result1 + result2
```

--------------------------------

### Register a workflow task with @app.task

Source: https://render.com/docs/workflows-sdk-python

Apply the @app.task decorator to a function to register it as a workflow task.

```python
from render import TaskContext, Workflows # highlight-line

app = Workflows() # highlight-line

@app.task # highlight-line
def calculate_square(ctx: TaskContext, a: int) -> int: # highlight-line
  return a * a
```

--------------------------------

### Parallel Task Execution in Python

Source: https://render.com/docs/workflows-defining

Uses asyncio.gather to execute multiple task runs concurrently within a workflow.

```python
from render import TaskContext, Workflows
import asyncio

app = Workflows()

@app.task
async def process_photo_upload(ctx: TaskContext, image_urls: list[str]) -> dict:
  # Process all images in parallel by chaining a run for each
  results = await asyncio.gather( # highlight-line
    *[ctx.run(process_image, url) for url in image_urls] # highlight-line
  ) # highlight-line

  num_successful = sum(1 for r in results if r["success"])
  num_failed = len(results) - num_successful

  return {
    "total": len(image_urls),
    "processed": num_successful,
    "failed": num_failed,
    "results": results
  }

@app.task
def process_image(ctx: TaskContext, image_url: str) -> dict:

  # Image processing logic goes here

  return {
    "url": image_url,
    "thumbnail_url": f"{image_url}_thumb.jpg",
    "success": True
  }
```

--------------------------------

### taskRunEvents(taskRunIds, signal, options)

Source: https://render.com/docs/workflows-sdk-typescript

Streams completion events for one or more task runs via Server-Sent Events (SSE).

```APIDOC
## taskRunEvents(taskRunIds, signal, options)

### Description
Streams completion events for one or more task runs. Returns an async iterator that yields a TaskRunDetails object each time a specified task run reaches a terminal status.

### Parameters
- **taskRunIds** (string[]) - Required - A list of task run IDs to stream events for.
- **signal** (AbortSignal) - Optional - AbortSignal to stop the stream.
- **options** (Object) - Optional - Reconnection settings (maxRetries, initialDelayMs, backoffFactor, maxDelayMs).

### Request Example
```typescript
for await (const event of render.workflows.taskRunEvents(['trn-1', 'trn-2'])) {
  console.log(event.status, event.id)
}
```
```
Tokens:
Raw