client.trigger - Upstash Documentation

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#

urlstringrequired#

The public URL of the workflow endpoint.

workflowRunIdstring#

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.

bodystring | object#

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

headersobject#

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

retriesstring#

Number of retry attempts for workflow steps. Default is 3.

retryDelaystring#

Delay between retries. Can use expressions like "1000 * (1 + retried)".

flowControlobject#

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

See Flow Control for details.

Show properties

keystring#

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

ratenumber#

The maximum number of allowed requests per second.

parallelismnumber#

The maximum number of concurrent requests allowed.

periodstring|number#

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

delaystring#

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").

notBeforenumber#

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.

labelstring | string[]#

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

Pass an array to attach multiple labels to a single workflow run. The run will then match a logs or DLQ filter for any of its labels (OR semantics).

disableTelemetryboolean#

If set to true, telemetry data collection for this workflow run will be disabled. By default, telemetry is enabled to help improve Upstash services.

See the disableTelemetry parameter in serve options for more details.

Usage#

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  retryDelay: "1000 * (1 + retried)", // optional delay between retries  delay: "10s"                  // optional delay value  failureUrl: "https://<YOUR_FAILURE_URL>", // optional failure url  flowControl: {                // optional flow control    key: "USER_GIVEN_KEY",    rate: 10,    parallelism: 5,    period: "10m"  },  label: ["team-a", "high-priority"], // optional label(s); single string or array})