Skip to main content
When you trigger a workflow, your workflow starts executing as a background job. Traditionally, the only way to check workflow status is by repeatedly calling client.logs to fetch the workflow state. However, this approach is slow and expensive. A better solution is to use Upstash Realtime, which enables you to emit events from your workflow and subscribe to them in real-time on your frontend.

​
How It Works

Upstash Realtime is powered by Upstash Redis and provides a simple API for publishing and subscribing to events:
  • When you emit an event, it’s instantly delivered to live subscribers and stored for later retrieval
  • Your frontend can subscribe to these events in real-time
  • You can also fetch events emitted in the past
This guide shows you how to integrate Upstash Workflow with Upstash Realtime to display real-time progress updates in your frontend.

​
Prerequisites

  • An Upstash account with:
    • A QStash project for workflows
    • A Redis database for Realtime
  • Next.js application set up

​
Setup

​
1. Install Dependencies

npm install @upstash/workflow @upstash/realtime @upstash/redis zod

​
2. Configure Upstash Realtime

Create a Realtime instance in lib/realtime.ts: 
import { InferRealtimeEvents, Realtime } from "@upstash/realtime";
import { Redis } from "@upstash/redis";
import z from "zod/v4";

const redis = Redis.fromEnv();

const schema = {
  workflow: {
    runFinish: z.object({}),
    stepFinish: z.object({
      stepName: z.string(),
      result: z.unknown().optional()
    }),
  }
}

export const realtime = new Realtime({ schema, redis })
export type RealtimeEvents = InferRealtimeEvents<typeof realtime>

​
3. Create a Realtime Endpoint

Create an API route at app/api/realtime/route.ts to handle Realtime connections: 
import { handle } from "@upstash/realtime";
import { realtime } from "@/lib/realtime";

export const maxDuration = 300;

export const GET = handle({ realtime });
This endpoint enables Server-Sent Events (SSE) connections for real-time updates.

​
4. Add the Realtime Provider

Wrap your application in the RealtimeProvider by updating your root layout at app/layout.tsx: 
"use client"

import { RealtimeProvider } from "@upstash/realtime/client";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <RealtimeProvider>{children}</RealtimeProvider>
      </body>
    </html>
  );
}

​
5. Create a Typed Client Hook

Create a typed useRealtime hook at lib/realtime-client.ts: 
"use client";

import { createRealtime } from "@upstash/realtime/client";
import type { RealtimeEvents } from "./realtime";

export const { useRealtime } = createRealtime<RealtimeEvents>();

​
Building the Workflow

​
1. Create the Workflow Endpoint

Create your workflow at app/api/workflow/basic/route.ts: 
import { serve } from "@upstash/workflow/nextjs";
import { realtime } from "@/lib/realtime";

type WorkflowPayload = {
  userId: string;
  action: string;
};

export const { POST } = serve<WorkflowPayload>(async (context) => {
  const { userId, action } = context.requestPayload;
  const workflowRunId = context.workflowRunId;

  // Create a channel based on the workflow run ID
  const channel = realtime.channel(workflowRunId);

  // Step 1: Data Validation
  await context.run("validate-data", async () => {
    // Your validation logic
    if (!userId || !action) {
      throw new Error("Missing required fields");
    }

    const result = { valid: true, userId, action };

    // sleep 500 ms
    await new Promise((resolve) => setTimeout(resolve, 500));

    // Emit step completion
    await channel.emit("workflow.stepFinish", {
      stepName: "validate-data",
      result,
    });

    return result;
  });


  // Additional steps follow the same pattern...

  // Emit run completion
  await context.run("run-finish", () => channel.emit("workflow.runFinish", {}) );

  return { success: true, workflowRunId };
});
Key points:
  • Use realtime.channel(workflowRunId) to create a unique channel per workflow run
  • Emit events after each step completes
  • Emit events inside context.run steps to ensure that they are emitted only once as the workflow executes.
  • Events are emitted to separate event names like workflow.stepFinish and workflow.runFinish

​
2. Create a Trigger Endpoint

Create an endpoint to trigger workflows at app/api/trigger/route.ts: 
import { NextRequest, NextResponse } from "next/server";
import { Client } from "@upstash/workflow";

export const workflowClient = new Client({
  token: process.env.QSTASH_TOKEN,
  baseUrl: process.env.QSTASH_URL,
});

export async function POST(request: NextRequest) {
  const body = await request.json() as { workflowType: string };
  const workflowUrl = `${request.nextUrl.origin}/api/workflow/${body.workflowType}`;

  const { workflowRunId } = await workflowClient.trigger({
    url: workflowUrl,
    body: {
      userId: "user-123",
      action: "process-data",
    },
  });

  return NextResponse.json({ workflowRunId });
}

​
Building the Frontend

​
1. Create a Custom Hook

Create a React hook to manage the Realtime subscription at hooks/useWorkflowWithRealtime.ts: 
"use client";

import { useRealtime } from "@/lib/realtime-client";
import { useState, useCallback } from "react";

interface WorkflowStep {
  stepName: string;
  result?: unknown;
}

export function useWorkflowWithRealtime() {
  const [workflowRunId, setWorkflowRunId] = useState<string | null>(null);
  const [steps, setSteps] = useState<WorkflowStep[]>([]);
  const [isTriggering, setIsTriggering] = useState(false);
  const [isRunFinished, setIsRunFinished] = useState(false);

  // Subscribe to workflow updates
  useRealtime({
    enabled: !!workflowRunId,
    channels: workflowRunId ? [workflowRunId] : [],
    events: ["workflow.stepFinish", "workflow.runFinish"],
    onData({ event, data }) {
      if (event === "workflow.stepFinish") {
        setSteps((prev) => [
          ...prev,
          {
            stepName: data.stepName,
            result: data.result,
          },
        ]);
      } else if (event === "workflow.runFinish") {
        setIsRunFinished(true);
      }
    },
  });

  const trigger = useCallback(async () => {
    setIsTriggering(true);
    setSteps([]);
    setIsRunFinished(false);

    const response = await fetch("/api/trigger", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ workflowType: "basic" }),
    });

    const data = await response.json();
    setWorkflowRunId(data.workflowRunId);
    setIsTriggering(false);
  }, []);

  return {
    trigger,
    isTriggering,
    workflowRunId,
    steps,
    isRunFinished,
  };
}
Key features:
  • Subscribe to multiple events using the events array: ["workflow.stepFinish", "workflow.runFinish"]
  • The hook manages both triggering the workflow and subscribing to updates
  • Type-safe event handling with TypeScript

​
2. Use the Hook in Your Component

"use client";

import { useWorkflowWithRealtime } from "@/hooks/useWorkflowWithRealtime";

export default function WorkflowPage() {
  const { trigger, isTriggering, steps, isRunFinished } = useWorkflowWithRealtime();

  return (
    <div style={{ maxWidth: "600px", margin: "40px auto", fontFamily: "Arial, sans-serif" }}>
      <button onClick={trigger} disabled={isTriggering}>
        {isTriggering ? "Starting..." : "Click to Trigger Workflow"}
      </button>

      {isRunFinished && (
        <h3 style={{ marginTop: "20px" }}>✅ Workflow Finished!</h3>
      )}

      <h3 style={{ marginTop: "20px" }}>Workflow Steps:</h3>

      <div>
        {steps.map((step, index) => (
          <div key={index}>
            <strong>{step.stepName}</strong>
            {Boolean(step.result) && <span>: {JSON.stringify(step.result)}</span>}
          </div>
        ))}
      </div>
    </div>
  );
}

​
How It All Works Together

  1. User triggers workflow: The frontend calls /api/trigger, which returns a workflowRunId
  2. Workflow executes: The workflow runs as a background job, emitting events at each step
  3. Frontend subscribes: Using the workflowRunId, the frontend subscribes to the Realtime channel
  4. Real-time updates: As the workflow emits events, they’re instantly delivered to the frontend via Server-Sent Events

​
Benefits Over Polling

Polling (client.logs)Realtime
Slow (requires HTTP requests)Instant (Server-Sent Events)
Expensive (repeated API calls)Efficient (single connection)
High latency (poll interval)Low latency (real-time)

​
Full Example

For a complete working example with all steps, error handling, and UI components, check out the Upstash Realtime example on GitHub.

​
Next Steps