Implementation:Langgenius Dify UseWorkflowRunHistory

Knowledge Sources	Dify
Domains	Workflow API Observability
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for retrieving workflow execution history and understanding execution status enumerations, provided by the Dify workflow service layer through a TanStack Query hook and companion TypeScript types.

Description

The workflow run history subsystem provides the query hook and type definitions needed to build execution monitoring interfaces:

useWorkflowRunHistory is a TanStack Query hook that fetches the execution history for a workflow. It accepts an optional URL parameter and an enabled flag, making it easy to conditionally fetch data only when the monitoring panel is open. The hook returns a WorkflowRunHistoryResponse containing an array of past execution records with their statuses, timings, and associated node traces.

WorkflowRunningStatus is a TypeScript enum that defines the five possible states for an overall workflow execution: Waiting, Running, Succeeded, Failed, and Stopped. These states are used by the UI to display status badges, color-code execution entries, and determine which actions are available (e.g., stop is only available for Running workflows).

NodeRunningStatus is a TypeScript enum that defines the nine possible states for an individual node execution: NotStart, Waiting, Listening, Running, Succeeded, Failed, Exception, Retry, and Stopped. These states drive the visual indicators on individual nodes during and after execution.

NodeTracing is the TypeScript type representing a single node's execution record, including its unique execution ID, the node definition ID, final status, elapsed time, resolved inputs, produced outputs, and any error information.

Usage

Use useWorkflowRunHistory to populate the run history panel in the workflow editor. Use the status enums to render appropriate visual indicators (colors, icons, badges) for workflow and node states. Use NodeTracing to type-check components that display execution details.

Code Reference

Source Location

• Repository: Dify
• Files:
  • web/service/use-workflow.ts (Lines 29-36) -- useWorkflowRunHistory
  • web/app/components/workflow/types.ts (Lines 347-353) -- WorkflowRunningStatus
  • web/app/components/workflow/types.ts (Lines 360-370) -- NodeRunningStatus

Signature

// Hook to fetch workflow execution history
export const useWorkflowRunHistory = (
  url?: string,
  enabled?: boolean
): UseQueryResult<WorkflowRunHistoryResponse>

// Workflow-level status enum
export enum WorkflowRunningStatus {
  Waiting = 'waiting',
  Running = 'running',
  Succeeded = 'succeeded',
  Failed = 'failed',
  Stopped = 'stopped',
}

// Node-level status enum
export enum NodeRunningStatus {
  NotStart = 'not-start',
  Waiting = 'waiting',
  Listening = 'listening',
  Running = 'running',
  Succeeded = 'succeeded',
  Failed = 'failed',
  Exception = 'exception',
  Retry = 'retry',
  Stopped = 'stopped',
}

Import

import { useWorkflowRunHistory } from '@/service/use-workflow'
import {
  WorkflowRunningStatus,
  NodeRunningStatus,
} from '@/app/components/workflow/types'

I/O Contract

Inputs (useWorkflowRunHistory)

Name	Type	Required	Description
url	string	No	The run history endpoint URL. The query is disabled when this is falsy.
enabled	boolean	No	Whether to fetch the data. Defaults to true. Set to false to suspend fetching (e.g., when the panel is closed).

Outputs (useWorkflowRunHistory)

Name	Type	Description
data	WorkflowRunHistoryResponse	The run history response containing an array of workflow execution records.
isLoading	boolean	Whether the query is currently fetching data.
isError	boolean	Whether the query encountered an error.
refetch	() => void	Function to manually trigger a re-fetch of the run history.

NodeTracing Type

Field	Type	Description
id	string	Unique identifier for this specific execution instance.
node_id	string	The definition ID of the node in the workflow graph.
status	NodeRunningStatus	The final execution status of the node.
elapsed_time	number	Wall-clock execution time in seconds.
inputs	Record<string, any>	The resolved input values that the node received.
outputs	Record<string, any>	The output values produced by the node.
error	null	Error message if the node failed; null on success.

Dependencies

Dependency	Purpose
@tanstack/react-query (useQuery)	Provides the reactive query hook with caching, conditional fetching, and automatic re-fetching.
@/service/base (get)	HTTP GET helper for fetching run history data.
@/types/workflow (WorkflowRunHistoryResponse)	TypeScript type definition for the run history API response.

Usage Examples

import { useWorkflowRunHistory } from '@/service/use-workflow'
import {
  WorkflowRunningStatus,
  NodeRunningStatus,
} from '@/app/components/workflow/types'

// Display run history in a monitoring panel
function RunHistoryPanel({ flowId, isOpen }) {
  const historyUrl = isOpen ? `/apps/${flowId}/workflow-runs` : undefined
  const { data, isLoading, refetch } = useWorkflowRunHistory(historyUrl, isOpen)

  if (isLoading) return <Spinner />

  return (
    <div>
      <button onClick={() => refetch()}>Refresh</button>
      {data?.data.map(run => (
        <div key={run.id}>
          <StatusBadge status={run.status} />
          <span>{run.elapsed_time}s</span>
          <span>{new Date(run.created_at * 1000).toLocaleString()}</span>
        </div>
      ))}
    </div>
  )
}

// Render a status badge with appropriate styling
function StatusBadge({ status }: { status: WorkflowRunningStatus }) {
  const colorMap = {
    [WorkflowRunningStatus.Waiting]: 'gray',
    [WorkflowRunningStatus.Running]: 'blue',
    [WorkflowRunningStatus.Succeeded]: 'green',
    [WorkflowRunningStatus.Failed]: 'red',
    [WorkflowRunningStatus.Stopped]: 'orange',
  }

  return <span style={{ color: colorMap[status] }}>{status}</span>
}

// Check individual node status in a trace
function NodeTrace({ trace }: { trace: NodeTracing }) {
  const isTerminal = [
    NodeRunningStatus.Succeeded,
    NodeRunningStatus.Failed,
    NodeRunningStatus.Exception,
    NodeRunningStatus.Stopped,
  ].includes(trace.status)

  return (
    <div>
      <span>{trace.node_id}: {trace.status}</span>
      {trace.error && <span className="error">{trace.error}</span>}
      {isTerminal && <span>Took {trace.elapsed_time}s</span>}
    </div>
  )
}

Related Pages

Implements Principle

• Principle:Langgenius_Dify_Workflow_Execution_Monitoring

Uses Heuristic

• Heuristic:Langgenius_Dify_SSE_Streaming_Error_Handling