client.trigger

The trigger method starts a new workflow run and returns its workflowRunId.

You can also trigger multiple workflow runs in a single call by passing an array of arguments instead of a single object.

Arguments

url · string · required

The public URL of the workflow endpoint.

workflowRunId · string

A custom identifier for the workflow run. Each run must use a unique ID.

The final ID will be prefixed with wfr_. For example: passing my-workflow results in wfr_my-workflow.

If omitted, a run ID will be generated automatically.

body · string | object

The request payload to pass into the workflow run. Accessible as context.requestPayload inside the workflow.

headers · object

HTTP headers to pass into the workflow run. Accessible as context.headers inside the workflow.

retries · string

retry to use in the initial request. in the rest of the workflow, retries option of the serve will be used.

retryDelay · string

delay between retries.

flowControl · object

An optional flow control configuration to limit concurrency and execution rate of the workflow runs.

See Flow Control for details.

Show properties

key · string

A logical grouping key that identifies which requests share the same flow control limits.

rate · number

The maximum number of allowed requests per second.

parallelism · number

The maximum number of concurrent requests allowed.

period · string|number

The time window used to enforce the defined rate limit. Default is 1s.

delay · string

Delay for the workflow run. This is used to delay the execution of the workflow run. The delay is in seconds or can be passed as a string with a time unit (e.g. “1h”, “30m”, ”15s”).

notBefore · number

Optionally set the absolute delay of this message. This will override the delay option. The message will not delivered until the specified time.

Unix timestamp in seconds.

useFailureFunction · bool

If both failureUrl and useFailureFunction are provided, useFailureFunction takes precedence and the value of the url parameter is used as failureUrl.

label · string

An optional label to assign to the workflow run. This can be useful for identifying and filtering runs in the dashboard or logs.

Usage

Single Workflow

import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" })

const { workflowRunId } = await client.trigger({
  url: "https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE>",
  body: "hello there!",         // optional body
  headers: { ... },             // optional headers
  workflowRunId: "my-workflow", // optional workflow run id
  retries: 3,                   // optional retries in the initial request
  retryDelay: "1000 * (1 + retried)", // optional delay between retries
  delay: "10s"                  // optional delay value
  failureUrl: "https://<YOUR_FAILURE_URL>", // optional failure url
  useFailureFunction: true,     // whether a failure function is defined in the endpoint
  flowControl: {                // optional flow control
    key: "USER_GIVEN_KEY",
    rate: 10,
    parallelism: 5,
    period: "10m"
  },
})