Start a Run - Upstash Documentation

You’ve defined your workflow, and the final step is to trigger the endpoint! There are two main ways to start your workflow:

Using `client.trigger` (Recommended)

We recommend using client.trigger to start your 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
  delay: "10s"                  // optional delay value
  failureUrl: "https://<YOUR_FAILURE_URL>", // optional failure url
  flowControl: { ... }          // optional flow control
})

console.log(workflowRunId)
// prints wfr_my-workflow

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

const client = new Client({ token: "<QSTASH_TOKEN>" })
const results = await client.trigger([
  {
    url: "<YOUR_WORKFLOW_ENDPOINT>",
    // other options...
  },
  {
    url: "<YOUR_WORKFLOW_ENDPOINT>",
    // other options...
  },
])

console.log(results[0].workflowRunId)
// prints wfr_my-workflow

2. Sending an HTTP Request

This approach is recommended for quick testing via curl during development. You should NOT start the workflow run in production by direct calls to your endpoint.

curl -X POST https://<YOUR_WORKFLOW_ENDPOINT>/<YOUR-WORKFLOW-ROUTE> \
   -H "my-header: foo" \
   -d '{"foo": "bar"}'

If you’ve secured your endpoint with signing keys, only the trigger method will work. Direct calls to the endpoint (e.g., via curl or fetch) will not be possible since Upstash-Signature header is missing.For more information, read Secure a workflow documentation.

Related topics

Handle Failed Runs TanStack Start Trigger Workflow Run Batch Trigger Workflow Runs Google Cloud Run functions

⌘I