Workflows SDK for TypeScript

Usage and symbol reference

The Render SDK for TypeScript provides support for:

Defining tasks and flows in your workflow service
Running functions as steps inside a flow
Chaining additional task runs from within a task function
Triggering and managing runs from TypeScript code outside the workflow

Install

From your TypeScript project directory:

shell

$ npm install @renderinc/sdk@latest

(Or pnpm install, bun add, etc.)

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

shell

$ npm install @renderinc/sdk@latest

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

Defining tasks

The following symbols pertain to creating and registering tasks in your workflow service. For usage guidance, see Defining Tasks.

`task(options, func)`

Use task() to register a provided function (func) as a workflow task with the specified options.

On success: Returns a task definition. You can pass this value to ctx.run() to chain runs of this task within another task.

typescript

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

// Example with all options
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
  }
)

Parameter Description

Function parameters

`options`

Required. An object containing configuration details for the task.

Only name is required. See all supported options below.

`func`

Required. The function to register as a task.

Supported options

`name`

Required. The task's name.

This affects the task's slug, which you use to reference the task when triggering runs.

Use a name that is unique across all tasks and flows in the workflow.

This value is not required to match the name of the function you provide as func.

`retry`

An object containing retry settings for the task. See all supported settings below.

If you omit this field, Render applies default task retry behavior.

`timeoutSeconds`

The timeout for each execution attempt, in seconds.

Must be between 30 seconds (30) and 24 hours (86400), inclusive.

The default value is 2 hours.

`plan`

The default compute plan to use for the task's runs.

One of the following:

CPU	RAM	Plan ID
Up to 1 CPU	Up to 4 GB	`flex`
2	4 GB	`2c-4g`
2	8 GB	`2c-8g`
4	8 GB	`4c-8g`
4	16 GB	`4c-16g`
8	32 GB	`8c-32g`

The default value is flex.

Providing starter or standard is equivalent to providing flex.

Retry settings

`maxRetries`

Required if you provide retry. The maximum number of retries to attempt for a given run of the task.

The total number of attempts is up to maxRetries + 1 (the initial attempt plus all retries).

`waitDurationMs`

Required if you provide retry. The base delay before attempting the first retry, in milliseconds.

`backoffScaling`

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 omit this field, the default value is 2.

The `TaskContext` object

Every task function must accept a TaskContext object as its first positional argument. Render automatically provides this object to each run (you do not provide it as an input).

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

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

On success: Returns a Promise that resolves with the chained run's return value.

Throws: RenderError, Error

It can also propagate ordinary errors if it cannot communicate with the task runtime.

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
  }
)

Parameter	Description
`task`	Required. The `task()`-registered function to run, such as `calculateSquare` in the example above.
`...args`	All input arguments to pass to the task run, as positional arguments: typescript ctx.run(sumSquares, 2, 3)

`TaskContext.metadata`

An object containing identifiers for the current task run and its execution chain.

Added in SDK v1.2.0.

Property Description

Property	Description
`taskRunId`	The ID of this task run.
`rootTaskRunId`	The ID of the root-level task run for this run's execution chain. If this run is the root-level run, this value is the same as `taskRunId`.
`parentTaskRunId`	The ID of the task run that chained this run. This value is `undefined` for a root-level run.

`taskRunId`

The ID of this task run.

`rootTaskRunId`

The ID of the root-level task run for this run's execution chain.

If this run is the root-level run, this value is the same as taskRunId.

`parentTaskRunId`

The ID of the task run that chained this run.

This value is undefined for a root-level run.

Defining flows

The following symbols pertain to creating and registering flows in your workflow service. For usage guidance, see Defining Flows.

`flow(options, func)`

Use flow() to register a provided function (func) as a flow with the specified options.

On success: Returns a flow definition.

typescript

import { flow, type FlowContext } from '@renderinc/sdk/workflows'

// Example with all options
const formatMessage = flow(
  {
    name: 'formatMessage',
    timeoutSeconds: 300,
    plan: 'flex'
  },
  async function formatMessage(ctx: FlowContext, message: string): Promise<string> {
    const trimmed = await ctx.step('trim', (text: string) => text.trim(), [message])
    const uppercase = await ctx.step('uppercase', (text: string) => text.toUpperCase(), [trimmed])
    return uppercase
  }
)

Parameter Description

Function parameters

`options`

Required. An object containing configuration details for the flow.

Only name is required. See all supported options below.

`func`

Required. The function to register as a flow.

Supported options

`name`

Required. The flow's name.

This affects the flow's slug, which you use to reference the flow when triggering runs.

Use a name that is unique across all tasks and flows in the workflow.

This value is not required to match the name of the function you provide as func.

`timeoutSeconds`

The timeout for each execution attempt, in seconds.

Must be between 30 seconds (30) and 24 hours (86400), inclusive.

The default value is 2 hours.

`plan`

The default compute plan to use for the flow's runs.

One of the following:

CPU	RAM	Plan ID
Up to 1 CPU	Up to 4 GB	`flex`
2	4 GB	`2c-4g`
2	8 GB	`2c-8g`
4	8 GB	`4c-8g`
4	16 GB	`4c-16g`
8	32 GB	`8c-32g`

The default value is flex.

Providing starter or standard is equivalent to providing flex.

The `FlowContext` object

Every flow function receives a FlowContext as its first positional argument. Render provides this object automatically.

For usage guidance, see Configuring step behavior.

`FlowContext.step(name, fn, args, options?)`

Runs a plain function as a step inside the flow's process.

On success: Returns a Promise that resolves with the function's return value.

Throws: StepError, DeterminismError, FlowFailedError, WorkflowLimitError, RenderError

typescript

const processOrder = flow(
  { name: 'processOrder' },
  async (ctx: FlowContext, orderId: string) => {
    const receipt = await ctx.step('chargeCard', chargeCard, [orderId], { 
      retry: { maxRetries: 3, waitDurationMs: 500 } 
    }) 
    return receipt
  }
)

Parameter	Description
Function parameters
`name`	Required. The step's name. This value is not required to match the name of the function you provide as `fn`.
`fn`	Required. The function to execute as a step. The function can return either a value or a Promise. The function's arguments and return value must be JSON-serializable. You must pass a plain function. You cannot pass a definition returned by `task()` or `flow()`.
`args`	Required if the function takes arguments. An array of positional argument values to pass to `fn`. For functions that take zero arguments, you can omit this array or provide `[]`.
`options`	Optional configuration details for the step. See all supported options below.
Supported `options`
`retry`	An object containing retry settings for this step. See all supported options below. If a step's return value fails JSON serialization, the step fails without retrying. If all attempts fail, `ctx.step()` throws a `StepError`. If this error is uncaught, the entire flow run fails. If you omit this field, the step is attempted once.
Retry settings
`maxRetries`	Required if you provide `retry`. The maximum number of retries after the initial attempt.
`waitDurationMs`	Required if you provide `retry`. The delay before the first retry, in milliseconds.
`backoffScaling`	The multiplier applied to `waitDurationMs` after each retry. The default value is `1.5`.

`FlowContext.metadata`

An object containing the current flow run's ID.

Property	Description
`flowRunId`	The ID of this flow run. Has the format `frn-abc123...`.

Triggering runs

These methods and types are related to triggering and managing runs of tasks and flows from any TypeScript code outside the workflow itself (web apps, scripts, and so on).

For full usage guidance, see Triggering Task Runs.

The `Render` class

The Render class provides client methods for triggering and managing task runs and flow runs. Initialize a Render object to call the Task methods and Flow methods.

Constructor

`Render(options)`

Initializes a Render SDK client.

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...'
})

Option Description

Option	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

These methods are available on the workflows attribute of a Render object.

`startTask(taskSlug, inputData, options?)`

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

On success: Returns a TaskRunResult object representing the started run. You can await the run's result by calling .get() on this object.

Throws: ClientError, ServerError, AbortError

typescript

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

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

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

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

`runTask(taskSlug, inputData, options?)`

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

On success: Returns a TaskRunDetails object for the finished task run. A failed or canceled run is returned with its terminal status; the SDK does not throw a TaskRunError for that status.

Throws: ClientError, ServerError, AbortError, Error

typescript

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

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

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 the wait for the run to complete. Canceling the client-side operation does not cancel the task run on Render. See Canceling operations with `AbortSignal`.

`listTaskRuns(params)`

Lists task runs that match optional filters.

On success: Returns an array of TaskRunWithCursor objects.

Throws: ClientError, ServerError

typescript

const taskRuns = await render.workflows.listTaskRuns({
  limit: 10,
  ownerId: ['tea-d3jm7ai4d50c73fale60']
})

for (const item of taskRuns) {
  console.log(item.taskRun.id, item.cursor)
}

Supported fields on params include:

Parameter	Description
`limit`	An integer specifying the maximum number of task runs to return.
`cursor`	A cursor string for pagination. Use this to retrieve the next page of results.
`taskSlug`	A list of task slugs to filter results by. Only task runs for these tasks are returned.
`rootTaskRunId`	A list of root task run IDs to filter results by. Only runs in these execution chains are returned.
`ownerId`	A list of workspace IDs to filter results by. Only task runs from these workspaces are returned.
`workflowVersionId`	A list of workflow version IDs to filter results by.
`workflowId`	A list of workflow IDs to filter results by.

`getTaskRun(taskRunId)`

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

On success: Returns a TaskRunDetails object.

Throws: ClientError, ServerError

typescript

const details = await render.workflows.getTaskRun('trn-abc123')
console.log(details.status, details.results)

Parameter Description

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

`taskRunId`

Required. The ID of the task run to retrieve.

Has the format trn-abc123...

`cancelTaskRun(taskRunId)`

Cancels the root-level task run with the specified ID, along with all of its chained runs. This throws a ClientError if the root-level run is not found.

Runs that have already finished are left unchanged.

On success: Returns void.

Throws: ClientError, ServerError

typescript

const startedRun = await render.workflows.startTask('my-workflow/calculateSquare', [99])
await render.workflows.cancelTaskRun(startedRun.taskRunId)

Parameter Description

Parameter	Description
`taskRunId`	Required. The ID of the root-level task run to cancel. Has the format `trn-abc123...`

`taskRunId`

Required. The ID of the root-level task run to cancel.

Has the format trn-abc123...

`taskRunEvents(taskRunIds, signal?, options?)`

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 reaches a terminal status.

As shown below, break out of the iterator loop after receiving events for all requested runs. The iterator does not automatically finish when all runs complete.

Throws: AbortError, Error

typescript

const run1 = await render.workflows.startTask('my-workflow/calculateSquare', [3])
const run2 = await render.workflows.startTask('my-workflow/calculateSquare', [6])

// Track which runs are still pending
const pending = new Set([run1.taskRunId, run2.taskRunId])

for await (const event of render.workflows.taskRunEvents([...pending])) {
  console.log(event.status, event.id, event.results)

  // Remove each run from the pending set when it reaches a terminal status
  pending.delete(event.id)

  // Break out of the loop when all runs have reached a terminal status
  if (pending.size === 0) break
}

Parameter	Description
`taskRunIds`	Required. A list of task run IDs to stream events for. Each ID has the format `trn-abc123...`
`signal`	Optional `AbortSignal` to stop the stream. For details, see Canceling operations with `AbortSignal`.
`options`	Optional reconnection settings for stream connection failures. See all supported options below.
Supported `options`
`maxRetries`	The maximum number of reconnection attempts after a stream connection failure. The default value is `5`.
`initialDelayMs`	The base delay before attempting the first reconnection, in milliseconds. The default value is `250`.
`backoffFactor`	The exponential backoff factor. After each reconnection attempt, the previous delay is multiplied by this factor, up to `maxDelayMs`. For example, a factor of `1.5` increases the delay by 50% after each reconnection attempt. The default value is `2`.
`maxDelayMs`	The maximum delay between reconnection attempts, in milliseconds. The default value is `16000`.

Flow methods

These methods are available on the workflows attribute of a Render object.

`startFlow(flowSlug, inputData, options?)`

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

To instead run a flow and wait for it to complete, use workflows.runFlow.

On success: Returns a FlowRun object representing the started run.

Throws: ClientError, ServerError, AbortError

typescript

// Trigger a run of formatMessage with an input of 'hello'
const startedRun = await render.workflows.startFlow(
  'my-workflow/formatMessage',
  ['hello'],
  { idempotencyKey: 'abc123' } // optional
)

const flowRunId: string = startedRun.id // Available immediately

Parameter	Description
Function parameters
`flowSlug`	Required. The slug indicating the flow to run, available from your flow's page in the Render Dashboard. 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. For a flow that takes zero arguments, 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`.

`runFlow(flowSlug, inputData, options?)`

Starts the registered flow 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.startFlow.

On success: Returns a FlowRunDetails object for the finished flow run. A failed or canceled run is returned with its terminal status; the SDK does not throw an error for that status.

Throws: ClientError, ServerError, AbortError, TypeError

typescript

const flowRun = await render.workflows.runFlow(
  'my-workflow/formatMessage',
  ['hello']
)

console.log(flowRun.status)
console.log(flowRun.results)

Parameter	Description
Function parameters
`flowSlug`	Required. The slug indicating the flow to run, available from your flow's page in the Render Dashboard. 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. For a flow that takes zero arguments, 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 and the wait for the run to complete. Canceling the client-side operation does not cancel the flow run on Render. See Canceling operations with `AbortSignal`.

`listFlowRuns(params?, signal?)`

Lists flow runs that match optional filters.

On success: Returns an array of FlowRunWithCursor objects.

Throws: ClientError, ServerError, AbortError

typescript

const flowRuns = await render.workflows.listFlowRuns({
  limit: 10,
  flowSlug: ['my-workflow/formatMessage']
})

for (const item of flowRuns) {
  console.log(item.flowRun.id, item.cursor)
}

Parameter	Description
Function parameters
`params`	An object containing filters and pagination settings. All fields are optional. See all supported fields below.
`signal`	An optional `AbortSignal` used to cancel the request. See Canceling operations with `AbortSignal`.
Supported `params`
`limit`	An integer specifying the maximum number of flow runs to return.
`cursor`	A cursor string for pagination. Use this to retrieve the next page of results.
`flowSlug`	A list of flow slugs to filter results by. Only flow runs for these flows are returned.
`flowId`	A list of flow definition IDs to filter results by.
`status`	A list of flow run status values to filter results by.
`ownerId`	A list of workspace IDs to filter results by. Only flow runs from these workspaces are returned.
`workflowVersionId`	A list of workflow version IDs to filter results by.
`workflowId`	A list of workflow IDs to filter results by.

`getFlowRun(flowRunId, signal?)`

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

On success: Returns a FlowRunDetails object.

Throws: ClientError, ServerError, AbortError

typescript

const details = await render.workflows.getFlowRun('frn-abc123')
console.log(details.status, details.results)

Parameter Description

Parameter	Description
`flowRunId`	Required. The ID of the flow run to retrieve. Has the format `frn-abc123...`
`signal`	An optional `AbortSignal` used to cancel the request. See Canceling operations with `AbortSignal`.

`flowRunId`

Required. The ID of the flow run to retrieve.

Has the format frn-abc123...

`signal`

An optional AbortSignal used to cancel the request.

See Canceling operations with AbortSignal.

`cancelFlowRun(flowRunId, signal?)`

Cancels the flow run with the specified ID.

On success: Returns void.

Throws: ClientError, ServerError, AbortError

typescript

const startedRun = await render.workflows.startFlow('my-workflow/formatMessage', ['hello'])
await render.workflows.cancelFlowRun(startedRun.id)

Parameter Description

Parameter	Description
`flowRunId`	Required. The ID of the flow run to cancel. Has the format `frn-abc123...`
`signal`	An optional `AbortSignal` used to cancel the request. See Canceling operations with `AbortSignal`.

`flowRunId`

Required. The ID of the flow run to cancel.

Has the format frn-abc123...

`signal`

An optional AbortSignal used to cancel the request.

See Canceling operations with AbortSignal.

Task types

`TaskAttempt`

Represents one execution attempt of a particular task run. Returned in a TaskRun object's attempts array.

Each run's initial attempt has "attempt number" 0. If an attempt fails and the run retries, each retry creates a new attempt with an incremented number.

Property Description

Property	Description
`taskRunId`	The ID of the task run this attempt belongs to.
`attempt`	The zero-based "attempt number": `0` for the initial attempt, `1` for the first retry, and so on.
`status`	The current status of this attempt, as a string. For possible values, see Run status.

`taskRunId`

The ID of the task run this attempt belongs to.

`attempt`

The zero-based "attempt number": 0 for the initial attempt, 1 for the first retry, and so on.

`status`

The current status of this attempt, as a string.

For possible values, see Run status.

`TaskAttemptDetails`

Provides the full details of an individual attempt. Returned in the TaskRunDetails.attempts array.

Includes all of the same properties as a TaskAttempt object, plus:

Property	Description
`error`	The error message if the attempt failed. Otherwise, this value is the empty string.
`results`	An array containing the attempt's return value, if it completed successfully. Otherwise, `null`.

`TaskRun`

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

The taskRun property of a TaskRunWithCursor returned by workflows.listTaskRuns

To get a run's full details including results, call workflows.getTaskRun with the run's ID to obtain a TaskRunDetails object.

Property	Description
`id`	The ID of the task run. Has the format `trn-abc123...`
`taskId`	The ID of the run's associated task. Has the format `tsk-abc123...`
`status`	The current status of the task run, as a string. See Run status for possible values.
`startedAt`	The timestamp when the task run was first created and queued for execution.
`completedAt`	The timestamp when the task run finished (successfully or otherwise). Present only if `status` is one of `completed`, `failed`, or `canceled`.
`parentTaskRunId`	The ID of this run's parent run, if this run was chained. For a root-level run, this value is the empty string.
`parentTaskAttempt`	The "attempt number" of the parent task run that chained this run. If chained from the parent run's initial attempt, this value is `0`. If chained from the parent run's first retry, this value is `1`, and so on. This field is not present for root-level runs.
`rootTaskRunId`	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`	An array of `TaskAttempt` objects representing each execution attempt so far.

`TaskRunDetails`

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

Calling the workflows.runTask method:

typescript

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

Calling .get() on a TaskRunResult returned by workflows.startTask:

typescript

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

Calling the workflows.getTaskRun method:

typescript

const taskRunDetails = await render.workflows.getTaskRun('trn-abc123')

Iterating over events from the workflows.taskRunEvents method

Includes all of the same properties as a TaskRun object, plus:

Property	Description
`results`	An array containing the task's return value(s). This value is `null` unless `status` is `completed`.
`input`	The argument values that were passed to the task run, in one of the following formats: An array with values matching the positional arguments of the task's function signature An object with keys matching the named arguments of the task's function signature The format matches whichever format the task input was originally provided in.
`error`	The error message if the task run failed. Present only if `status` is `failed`.
`attempts`	An array of `TaskAttemptDetails` objects representing each individual execution attempt for this run.

`TaskRunResult`

Represents a started task run before its completion.

You typically obtain a TaskRunResult from workflows.startTask, which kicks off a task run without waiting for it to finish.

Member Description

Member	Description
`taskRunId`	The started task run's ID, available immediately.
`get()`	Waits for completion and returns a `TaskRunDetails` object. Subsequent calls to `get()` return the same Promise, even if the Promise has already resolved or rejected.

`taskRunId`

The started task run's ID, available immediately.

`get()`

Waits for completion and returns a TaskRunDetails object.

Subsequent calls to get() return the same Promise, even if the Promise has already resolved or rejected.

`TaskRunWithCursor`

Represents an item returned by workflows.listTaskRuns. It pairs a task run with the cursor for that item.

Property	Description
`taskRun`	The `TaskRun` returned in this item.
`cursor`	The cursor associated with this item. Provide it as `cursor` in a subsequent `listTaskRuns()` call to continue listing task runs.

Flow types

`FlowRun`

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

Calling the workflows.startFlow method
The flowRun property of a FlowRunWithCursor returned by workflows.listFlowRuns

To get a run's full details including results, call workflows.getFlowRun with the run's ID to obtain a FlowRunDetails object.

Property	Description
`id`	The ID of the flow run. Has the format `frn-abc123...`
`flowId`	The ID of the run's associated flow. Has the format `flw-abc123...`
`status`	The current status of the flow run, as a string. See Flow run status for possible values.
`startedAt`	The timestamp when the flow run was first created and queued for execution.
`completedAt`	The timestamp when the flow run finished (successfully or otherwise). Present only if `status` is one of `succeeded`, `failed`, or `canceled`.

`FlowRunDetails`

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

Calling the workflows.runFlow method:

typescript

const flowRunDetails = await render.workflows.runFlow('my-workflow/formatMessage', ['hello'])

Calling the workflows.getFlowRun method:

typescript

const flowRunDetails = await render.workflows.getFlowRun('frn-abc123')

Includes all of the same properties as a FlowRun object, plus:

Property	Description
`results`	An array containing the flow's return value(s). This value is an empty array unless `status` is `succeeded`.
`input`	The argument values that were passed to the flow run, in one of the following formats: An array with values matching the positional arguments of the flow's function signature An object with keys matching the named arguments of the flow's function signature The format matches whichever format the flow input was originally provided in.
`error`	The error message if the flow run failed. Present only if `status` is `failed`.
`errorDetails`	Details for a determinism or limit error. See fields below.
`attempts`	An array of objects representing each individual execution attempt for this run. See all supported fields below.
`attempts` fields
`attempt`	The zero-based "attempt number": `0` for the initial attempt, `1` for the first recovery attempt, and so on.
`status`	The current status of this attempt, as a string. For possible values, see Flow run status.
`startedAt`	The timestamp when the attempt started executing.
`completedAt`	The timestamp when the attempt finished (successfully or otherwise). Present only if `status` is one of `succeeded`, `failed`, or `canceled`.
`error`	The error message if the attempt failed. Otherwise, this field is not present.
`errorDetails` fields
`code`	The error code: `flow_determinism_error`, `flow_step_limit_exceeded`, `flow_payload_too_large`, or `flow_history_too_large`.
`message`	A description of the failure.
`seq`	The zero-based sequence number of the step that caused the determinism error.
`flowAttempt`	The zero-based "attempt number" associated with the determinism error.
`kind`	For determinism errors: `input_hash` (name or input changed), `type`, or `unknown_type`.
`expected, actual`	Descriptions of the recorded and attempted calls for a determinism error.
`limit, value`	The applicable limit and the value that exceeded it.

`FlowRunStatus`

The string enum for a flow run's status, with one of the following values.

A successful flow run has status succeeded (task runs use completed). The terminal statuses are succeeded, failed, and canceled.

typescript

import { FlowRunStatus } from '@renderinc/sdk/workflows'

const flowRun = await render.workflows.getFlowRun('frn-abc123')

if (flowRun.status === FlowRunStatus.SUCCEEDED) {
  console.log(flowRun.results)
}

Value	Description
`pending`	The run has been queued but has not yet started executing.
`running`	The run is currently executing.
`succeeded`	The run finished successfully.
`failed`	The run finished with an error.
`canceled`	The run was canceled before it finished.

`FlowRunWithCursor`

Represents an item returned by workflows.listFlowRuns. It pairs a flow run with the cursor for that item.

Property	Description
`flowRun`	The `FlowRun` returned in this item.
`cursor`	The cursor associated with this item. Provide it as `cursor` in a subsequent `listFlowRuns()` call to continue listing flow runs.

Run status

The status field on TaskRun, TaskRunDetails, TaskAttempt, and TaskAttemptDetails is a string with one of the following values.

The exact meaning of each value differs for a task attempt and a task run, as shown:

Value	Task attempt	Task run
`pending`	The attempt has been queued but has not yet started executing.	The run's current attempt is `pending`.
`running`	The attempt is currently executing.	The run's current attempt is `running`.
`paused`	The attempt is waiting for the result of a chained run.	The run's current attempt is `paused`.
`completed`	The attempt finished successfully.	The run finished successfully.
`failed`	The attempt finished with an error.	All of the run's attempts have finished with an error and no retries remain.
`canceled`	The run was canceled before this attempt finished.	The run was canceled before it finished.

Canceling operations with `AbortSignal`

The startTask, runTask, startFlow, and runFlow methods accept a signal field in their options object. The other flow client methods accept a signal as their final parameter. taskRunEvents accepts an AbortSignal as its second parameter. Use a signal to stop a method call that is no longer needed, such as a request that exceeds a frontend timeout.

typescript

const controller = new AbortController()

// Set a 30-second timeout for the entire operation
const timeout = setTimeout(() => controller.abort(), 30_000)

try {
  const result = await render.workflows.runTask(
    'my-workflow/processData',
    [largeDataset],
    { signal: controller.signal }
  )
  console.log(result.status, result.results)
} catch (err) {
  if (err instanceof AbortError) {
    console.log('Operation timed out or was canceled')
  }
} finally {
  clearTimeout(timeout)
}

When a signal is passed to startTask, it applies to both the initial HTTP request and any subsequent wait via TaskRunResult.get(). This means a single AbortController can cancel the full lifecycle of starting a task and waiting for its result.

Terminating a client-side method call does not cancel the corresponding run. Runs continue executing on Render until they complete, time out, or are canceled with workflows.cancelTaskRun or workflows.cancelFlowRun.

Error types

The Render SDK defines the custom error types below. In certain cases, the SDK also throws native JavaScript errors, such as errors from network requests or event streams.

typescript

import {
  RenderError,
  ClientError,
  ServerError,
  AbortError
} from '@renderinc/sdk'

Client and task errors

`RenderError` `extends Error`

The base class for ClientError and ServerError.

Also raised in the following cases:

The client is missing an API token.
A call to ctx.run() references an unregistered task.
A chained task run fails.
Flow registration includes a retry policy, or a step call has invalid parameters.

`ClientError` `extends RenderError`

Raised when a request to the Render API returns a 400-level error code.

Common causes include:

Invalid API key
Invalid task or flow identifier
Invalid task or flow arguments
Invalid action (for example, starting a run on a suspended workflow service)

`ServerError` `extends RenderError`

Raised when a request to the Render API returns a 500-level error code.

`AbortError` `extends Error`

Raised when an SDK operation is canceled with an AbortSignal.

Flow execution errors

These errors are raised during flow execution, such as during a call to ctx.step().

Import these errors from @renderinc/sdk/workflows.

`StepError` `extends Error`

Raised when all attempts of a step fail. If uncaught, this error fails the flow run.

For retry guidance, see Retry settings.

Property	Description
`message`	The original error message.
`errorName`	The original error's name, such as `TypeError`.
`data`	Additional fields from the original error, when they can be serialized.

`DeterminismError` `extends RenderError`

Raised when a step call does not match the recorded history during replay. This fails the flow run even if flow code catches the error.

When available, the details object contains the following:

Property	Description
`step_key.seq`	The zero-based sequence number of the step that caused the determinism error.
`workflow_attempt`	The zero-based "attempt number" associated with the recorded step.
`kind`	How the replay differs from the recorded history: `input_hash`: The step's name or inputs changed. `type`: The type of step changed. `unknown_type`: The recorded step type is not recognized by the SDK.
`expected`	A description of the call recorded in the step history.
`actual`	A description of the call made during replay.

`FlowFailedError` `extends RenderError`

Raised when the flow cannot continue, such as when a step operation is rejected. The flow run fails even if flow code catches the error.

`WorkflowLimitError` `extends FlowFailedError`

Raised when a step operation exceeds a workflow limit. The flow run fails even if flow code catches the error.

The reason identifies the limit. The limit and value properties are included when supplied by the runtime.

Install

Defining tasks

task(options, func)

options

func

name

retry

timeoutSeconds

plan

maxRetries

waitDurationMs

backoffScaling

The TaskContext object

TaskContext.run(task, ...args)

task

...args

TaskContext.metadata

taskRunId

rootTaskRunId

parentTaskRunId

Defining flows

flow(options, func)

options

func

name

timeoutSeconds

plan

The FlowContext object

FlowContext.step(name, fn, args, options?)

name

fn

args

options

retry

maxRetries

waitDurationMs

backoffScaling

FlowContext.metadata

flowRunId

Triggering runs

The Render class

Constructor

Render(options)

token

Task methods

startTask(taskSlug, inputData, options?)

taskSlug

inputData

options

idempotencyKey

signal

runTask(taskSlug, inputData, options?)

taskSlug

inputData

options

idempotencyKey

signal

listTaskRuns(params)

limit

cursor

taskSlug

rootTaskRunId

ownerId

workflowVersionId

workflowId

getTaskRun(taskRunId)

taskRunId

cancelTaskRun(taskRunId)

taskRunId

taskRunEvents(taskRunIds, signal?, options?)

taskRunIds

signal

options

maxRetries

initialDelayMs

backoffFactor

maxDelayMs

Flow methods

startFlow(flowSlug, inputData, options?)

flowSlug

`task(options, func)`

`options`

`func`

`name`

`retry`

`timeoutSeconds`

`plan`

`maxRetries`

`waitDurationMs`

`backoffScaling`

The `TaskContext` object

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

`task`

`...args`

`TaskContext.metadata`

`taskRunId`

`rootTaskRunId`

`parentTaskRunId`

`flow(options, func)`

`options`

`func`

`name`

`timeoutSeconds`

`plan`

The `FlowContext` object

`FlowContext.step(name, fn, args, options?)`

`name`

`fn`

`args`

`options`

`retry`

`maxRetries`

`waitDurationMs`

`backoffScaling`

`FlowContext.metadata`

`flowRunId`

The `Render` class

`Render(options)`

`token`

`startTask(taskSlug, inputData, options?)`

`taskSlug`

`inputData`

`options`

`idempotencyKey`

`signal`

`runTask(taskSlug, inputData, options?)`

`taskSlug`

`inputData`

`options`

`idempotencyKey`

`signal`

`listTaskRuns(params)`

`limit`

`cursor`

`taskSlug`

`rootTaskRunId`

`ownerId`

`workflowVersionId`

`workflowId`

`getTaskRun(taskRunId)`

`taskRunId`

`cancelTaskRun(taskRunId)`

`taskRunId`

`taskRunEvents(taskRunIds, signal?, options?)`

`taskRunIds`

`signal`

`options`

`maxRetries`

`initialDelayMs`

`backoffFactor`

`maxDelayMs`

`startFlow(flowSlug, inputData, options?)`

`flowSlug`

`inputData`

`options`

`idempotencyKey`

`signal`

`runFlow(flowSlug, inputData, options?)`

`flowSlug`

`inputData`