Triggering Workflow Runs

Kick off your registered tasks and flows.

Triggering one task run from another?

Use run chaining instead of the methods below. For details, see Chaining task runs.

After you create a workflow and register its tasks and flows, you can start triggering runs from your own apps and agents.

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

First: Create an API key

Triggering runs from code requires a Render API key.

Create an API key from your Account Settings page in the Render Dashboard. Copy and securely store the key, which is displayed in full only on creation.

API keys are secret credentials!

Don't publicly post your API key, commit it to version control, or otherwise share it with anyone outside your organization. If you believe an API key has been compromised, revoke it.

Running with the Render SDK

The Render SDK is currently available for TypeScript and Python.

SDKs for additional languages are planned for future releases. To trigger runs from other languages, use the Render API.

Follow these steps to trigger runs from your code using the Render SDK.

1. Install the SDK

From your TypeScript project directory:

(Or pnpm install, bun add, etc.)

If you already have the SDK installed, make sure you're using version 1.7.0 or later:

After installing, make sure @renderinc/sdk is listed as a dependency in your package.json file at version ^1.7.0 or later.

From your Python project directory:

If you already have the SDK installed, make sure you're using version 1.7.0 or later:

After installing, make sure to add render>=1.7.0 as a dependency in your application's requirements.txt, pyproject.toml, 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 when initializing the client (see your language's SDK reference for details). Do not hardcode your API key in your code.

3. Initialize the client

Initialize the SDK client you’ll use to trigger and manage runs:

4. Trigger a task run

Using the client initialized above, this code demonstrates triggering a task run and waiting for it to complete:

You trigger a task run by calling the client's workflows.startTask method. This method has the following parameters:

Parameter	Description
Function parameters
`taskSlug`	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/calculateSquare`).
`inputData`	Required. An array containing the task's input arguments. Elements are positional based on the task's function signature. For a task that takes zero arguments, provide an empty array, `[]`.
`options`	An object containing configuration options for the task run. All fields are optional. See all supported options below.
Supported `options`
`idempotencyKey`	An optional string used to prevent duplicate task runs. Added in SDK v1.2.0. For details, see Idempotency keys.
`signal`	An optional `AbortSignal` used to cancel the initial request and any subsequent wait via `TaskRunResult.get()`. Canceling the client-side operation does not cancel the task run on Render. See Canceling operations with `AbortSignal`.

The workflows.startTask method returns a TaskRunResult as soon as the run is created. This object provides the run's taskRunId immediately. You can call await result.get() to wait for the run to complete and obtain the full run details (including status and results).

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

You trigger a task run by calling the async client's workflows.start_task method. This method has the following parameters:

Parameter Description

Parameter	Description
`task_slug`	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, `[]`.
`idempotency_key`	An optional string used to prevent duplicate task runs. Added in SDK v1.2.0. For details, see Idempotency keys.

`task_slug`

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, [].

`idempotency_key`

An optional string used to prevent duplicate task runs.

Added in SDK v1.2.0.

For details, see Idempotency keys.

The workflows.start_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 and obtain a TaskRunDetails object.

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

You trigger a task run by calling the synchronous client's workflows.start_task method. This method has the following parameters:

Parameter Description

Parameter	Description
`task_slug`	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, `[]`.
`idempotency_key`	An optional string used to prevent duplicate task runs. Added in SDK v1.2.0. For details, see Idempotency keys.

`task_slug`

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, [].

`idempotency_key`

An optional string used to prevent duplicate task runs.

Added in SDK v1.2.0.

For details, see Idempotency keys.

The workflows.start_task method returns a TaskRun object as soon as the run is created. This object provides the run's id and initial status, which are both available immediately.

To wait for the run to complete, pass its ID to workflows.task_run_events. The iterator yields a TaskRunDetails object when the run reaches a terminal status (completed, failed, or canceled). You can also use workflows.run_task instead of start_task to start and wait in one blocking call.

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

5. Trigger a flow run

Using the client initialized above, this code demonstrates triggering a flow run and waiting for it to complete:

You trigger a flow run by calling the client's workflows.startFlow method. This method has the following parameters:

Parameter	Description
Function parameters
`flowSlug`	Required. The slug indicating the flow to run, available from your flow's page in the Render Dashboard. Always has the format `{workflow-slug}/{flow-name}` (e.g., `my-workflow/formatMessage`).
`inputData`	Required. An array containing the flow's input arguments. Elements are positional based on the flow's function signature. Do not include a value for `ctx`. Render provides the `FlowContext` object automatically. For a flow that takes no arguments besides `ctx`, provide an empty array, `[]`.
`options`	An object containing configuration options for the flow run. All fields are optional. See all supported options below.
Supported `options`
`idempotencyKey`	An optional string used to prevent duplicate flow runs. For details, see Idempotency keys.
`signal`	An optional `AbortSignal` used to cancel the initial request. Canceling the client-side operation does not cancel the flow run on Render. See Canceling operations with `AbortSignal`.

The workflows.startFlow method returns a FlowRun object as soon as the run is created. This object provides the run's id and initial status, which are both available immediately.

To wait for the run to complete, poll workflows.getFlowRun with its ID until the run reaches a terminal status (succeeded, failed, or canceled). This method returns a FlowRunDetails object, including status and results. You can also use workflows.runFlow instead of startFlow to start and wait in one call.

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

You trigger a flow run by calling the async client's workflows.start_flow method. This method has the following parameters:

Parameter Description

Parameter	Description
`flow_slug`	Required. The slug indicating the flow to run, available from your flow's page in the Render Dashboard. Always has the format `{workflow-slug}/{flow-name}` (e.g., `my-workflow/format_message`).
`input_data`	Required. A list or dictionary containing the flow's input arguments. If you provide a list, elements are positional based on the flow's function signature. If you provide a dictionary, each key maps to a parameter name in the flow's function signature. Do not include a value for `ctx`. Render provides the `FlowContext` object automatically. For a flow that takes no arguments besides `ctx`, provide an empty list, `[]`.
`idempotency_key`	An optional string used to prevent duplicate flow runs. For details, see Idempotency keys.

`flow_slug`

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

Always has the format {workflow-slug}/{flow-name} (e.g., my-workflow/format_message).

`input_data`

Required. A list or dictionary containing the flow's input arguments.

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

Do not include a value for ctx. Render provides the FlowContext object automatically.

For a flow that takes no arguments besides ctx, provide an empty list, [].

`idempotency_key`

An optional string used to prevent duplicate flow runs.

For details, see Idempotency keys.

The workflows.start_flow method returns a FlowRun object as soon as the run is created. This object provides the run's id and initial status, which are both available immediately.

To wait for the run to complete, poll workflows.get_flow_run with its ID until the run reaches a terminal status (succeeded, failed, or canceled). This method returns a FlowRunDetails object, including status and results.

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

You trigger a flow run by calling the synchronous client's workflows.start_flow method. This method has the following parameters:

Parameter Description

Parameter	Description
`flow_slug`	Required. The slug indicating the flow to run, available from your flow's page in the Render Dashboard. Always has the format `{workflow-slug}/{flow-name}` (e.g., `my-workflow/format_message`).
`input_data`	Required. A list or dictionary containing the flow's input arguments. If you provide a list, elements are positional based on the flow's function signature. If you provide a dictionary, each key maps to a parameter name in the flow's function signature. Do not include a value for `ctx`. Render provides the `FlowContext` object automatically. For a flow that takes no arguments besides `ctx`, provide an empty list, `[]`.
`idempotency_key`	An optional string used to prevent duplicate flow runs. For details, see Idempotency keys.

`flow_slug`

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

Always has the format {workflow-slug}/{flow-name} (e.g., my-workflow/format_message).

`input_data`

Required. A list or dictionary containing the flow's input arguments.

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

Do not include a value for ctx. Render provides the FlowContext object automatically.

For a flow that takes no arguments besides ctx, provide an empty list, [].

`idempotency_key`

An optional string used to prevent duplicate flow runs.

For details, see Idempotency keys.

The workflows.start_flow method returns a FlowRun object as soon as the run is created. This object provides the run's id and initial status, which are both available immediately.

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

Other supported methods

Running with the Render API

The Render API provides endpoints for triggering runs, along with a variety of endpoints for retrieving workflow and run details. The Render 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 task endpoint. The JSON body for this request includes the following properties:

Property Description

Property	Description
`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: 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. An array containing values for the task's input arguments. Elements are positional based on the task's function signature. For a task that takes zero arguments, provide an empty array, `[]`.
`idempotencyKey`	An optional string used to prevent duplicate runs. For details, see Idempotency keys.

`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. An array containing values for the task's input arguments.

Elements are positional based on the task's function signature.

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

`idempotencyKey`

An optional string used to prevent duplicate runs.

For details, see Idempotency keys.

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

Property Description

Property	Description
`flow`	Required. An identifier specifying the flow to run. You can provide either of two identifiers, both of which are available from your flow's page in the Render Dashboard: The flow's slug This has the format `{workflow-slug}/{flow-name}` (for example, `my-workflow/format_message`) The flow's ID This has the format `flw-abc123...`
`input`	Required. An array containing values for the flow's input arguments. Elements are positional based on the flow's function signature. Do not include a value for `ctx`. Render provides the `FlowContext` object automatically. For a flow that takes no arguments besides `ctx`, provide an empty array, `[]`.
`idempotencyKey`	An optional string used to prevent duplicate runs. For details, see Idempotency keys.

`flow`

Required. An identifier specifying the flow to run.

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

The flow's slug
- This has the format {workflow-slug}/{flow-name} (for example, my-workflow/format_message)
The flow's ID
- This has the format flw-abc123...

`input`

Required. An array containing values for the flow's input arguments.

Elements are positional based on the flow's function signature.

Do not include a value for ctx. Render provides the FlowContext object automatically.

For a flow that takes no arguments besides ctx, provide an empty array, [].

`idempotencyKey`

An optional string used to prevent duplicate runs.

For details, see Idempotency keys.

Running manually

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

Running manually in the Render Dashboard

From your workflow's Definitions page in the Render Dashboard, click any task or flow to open its Runs page.
Click Run Task / Run Flow in the top-right corner of the page:

A dialog appears for providing the run's input arguments:
Provide the run's input arguments as a JSON array. Each array element maps to the task/flow function's corresponding positional argument.

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

You can click Format and Validate to cleanly structure your input and confirm that it's valid JSON.
Click Run task / Run flow.

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

Running tasks manually with the Render CLI

Make sure your development machine has version 2.35.0 or later of the Render CLI:

If it doesn't, install the latest version.
Installation instructions

Use any of the following methods to install the Render CLI or upgrade to the latest version:
Homebrew installation

Run the following commands:

WinGet installation

Run the following command:

Installing with curl

Run the following command:
Direct download

Open the CLI's GitHub releases page.

Download the executable that corresponds to your system's architecture.

If you use an architecture besides those provided, you can build from source instead.
Building from source

We recommend building from source only if no other installation method works for your system.

Install the Go programming language if you haven't already.

Clone and build the CLI project with the following commands:
After installation completes, open a new terminal tab and run render with no arguments to confirm.
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 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:

Running flows manually with the Render CLI

Make sure your development machine has version 2.35.0 or later of the Render CLI:

If it doesn't, install the latest version.
Installation instructions

Use any of the following methods to install the Render CLI or upgrade to the latest version:
Homebrew installation

Run the following commands:

WinGet installation

Run the following command:

Installing with curl

Run the following command:
Direct download

Open the CLI's GitHub releases page.

Download the executable that corresponds to your system's architecture.

If you use an architecture besides those provided, you can build from source instead.
Building from source

We recommend building from source only if no other installation method works for your system.

Install the Go programming language if you haven't already.

Clone and build the CLI project with the following commands:
After installation completes, open a new terminal tab and run render with no arguments to confirm.
List the flows available in your active workspace:

Note your flow's Name and Workflow ID. Then list workflows as JSON to obtain their slugs:

Find the workflow object with the matching id and note its slug.
Start a run by providing the flow's slug and its input arguments as a JSON array:
- Replace my-workflow/format_message with {workflow-slug}/{flow-name}, using the workflow slug and flow name from the previous step.
- For a flow that takes zero input arguments, provide --input='[]'.
The CLI prints the new run's ID, which has the format frn-abc123....
List runs for the flow:
Inspect a run's status and, after it finishes, its return value:

Replace frn-abc123 with the ID of the run to inspect.

For all supported commands and options, see the CLI reference.

Idempotency keys

You can provide an idempotency key when triggering a run with the Render SDK or API. This helps prevent accidental creation of duplicate runs.

Task idempotency keys were added in SDK v1.2.0.

Provide idempotencyKey in the options object for any of startTask, runTask, startFlow, or runFlow:

Task idempotency keys were added in SDK v1.2.0.

Provide the idempotency_key keyword parameter to any of start_task, run_task, start_flow, or run_flow. Both synchronous and asynchronous clients support this parameter:

Include idempotencyKey in the JSON body of your request to the Run task or Run flow endpoint:

Idempotency keys are useful when resubmitting a request after a timeout, or when handling an incoming event that might be delivered more than once.

How idempotency works

If you include an idempotency key when triggering a run, your workflow service checks whether it has already created a run with the same idempotency key in the last 24 hours:

If so, Render responds with the original run instead of creating a new one.
If not, Render creates a new run and associates the idempotency key with it.

Considerations

When creating and using idempotency keys, keep the following in mind:

Keys are scoped to a workflow service.

Two different workflow services in your workspace can use the same idempotency key independently.
The original task/flow and its inputs are always preserved.

If you provide the same idempotency key but specify a different task/flow or different arguments, Render still responds with the original run.

This is true even if you originally ran a task and are now attempting to run a flow with the same idempotency key (or vice versa).
Idempotency is enforced for 24 hours from a run's creation.

Repeated trigger attempts do not extend this window. Completion, failure, or cancellation of a run does not shorten this window. After the window expires, reusing the key creates a new run, even if the original run is still executing.
Idempotency does not affect retry or replay logic.

Idempotency keys serve only to prevent duplicate creation of a root-level run:
- A single task run might still execute multiple attempts according to its retry configuration.
- A single flow run might still replay if it's interrupted.
Always design any side effects in your tasks and flows to handle repeated execution attempts.

First: Create an API key

Running with the Render SDK

1. Install the SDK

2. Set your API key

3. Initialize the client

4. Trigger a task run

taskSlug

inputData

options

idempotencyKey

signal

task_slug

input_data

idempotency_key

task_slug

input_data

idempotency_key

5. Trigger a flow run

flowSlug

inputData

options

idempotencyKey

signal

flow_slug

input_data

idempotency_key

flow_slug

input_data

idempotency_key

Other supported methods

Running with the Render API

task

input

idempotencyKey

flow

input

idempotencyKey

Running manually

Running manually in the Render Dashboard

Running tasks manually with the Render CLI

Homebrew installation

WinGet installation

Installing with curl

Direct download

Building from source

Running flows manually with the Render CLI

Homebrew installation

WinGet installation

Installing with curl

Direct download

Building from source

Idempotency keys

How idempotency works

Considerations

Triggering Workflow Runs

`taskSlug`

`inputData`

`options`

`idempotencyKey`

`signal`

`task_slug`

`input_data`

`idempotency_key`

`task_slug`

`input_data`

`idempotency_key`

`flowSlug`

`inputData`

`options`

`idempotencyKey`

`signal`

`flow_slug`

`input_data`

`idempotency_key`

`flow_slug`

`input_data`

`idempotency_key`

`task`

`input`

`idempotencyKey`

`flow`

`input`

`idempotencyKey`

Installing with `curl`

Installing with `curl`