WorkflowHistory

Query workflow history events for specific executions

Audience: Programmer

Fetches workflow history events for executions matching the filter criteria. This query is designed to retrieve the complete history for specific workflow executions, replacing the removed history field from WorkflowExecutionInfo.

Use this query when you need to inspect workflow execution details, debug workflow behavior, or display workflow event timelines.

Arguments

Name	Type	Description
where	WorkflowExecutionsWhereInput!	Filter criteria for workflow executions (required)
limit	Int	Maximum number of executions to fetch history for. Defaults to 10, max 100

Return Type

WorkflowExecutionHistoryConnection! - A connection containing workflow executions with their history events.

Connection Fields

Field	Type	Description
edges	[WorkflowExecutionHistoryEdge!]!	List of workflow execution history edges
pageInfo	WorkflowPageInfo!	Pagination information
totalCount	Int!	Total count of matching executions

Edge Fields

Field	Type	Description
node	WorkflowExecutionHistory!	The workflow execution with history
cursor	String!	Cursor for pagination

WorkflowExecutionHistory Fields

Field	Type	Description
execution	WorkflowExecution!	The workflow execution identifier
typeName	String!	The workflow type name
history	[WorkflowEvent!]!	All history events for this execution

Filter Options

The where parameter accepts the same WorkflowExecutionsWhereInput as the workflowExecutions query. Common filters for history retrieval include:

Filter	Type	Description
workflowID	String	Exact workflow ID (recommended for single execution)
runID	String	Specific run ID
workflowIDIn	[String!]	Multiple workflow IDs
typeName	String	Filter by workflow type
status	String	Filter by status

Usage Examples

Get History for a Single Execution

query {
  workflowHistory(
    where: {
      workflowID: "picking-order-12345"
    }
  ) {
    edges {
      node {
        execution {
          workflowId
          id
        }
        typeName
        history {
          eventId
          eventTime
          eventType
          extra
        }
      }
    }
    totalCount
  }
}

Get History for Specific Run

query {
  workflowHistory(
    where: {
      workflowID: "picking-order-12345"
      runID: "run-abc-123"
    }
  ) {
    edges {
      node {
        execution {
          workflowId
          id
        }
        typeName
        history {
          eventId
          eventTime
          eventType
          extra
        }
      }
    }
  }
}

Get History for Multiple Executions

query {
  workflowHistory(
    where: {
      workflowIDIn: [
        "picking-order-12345",
        "picking-order-12346",
        "picking-order-12347"
      ]
    }
    limit: 10
  ) {
    edges {
      node {
        execution {
          workflowId
          id
        }
        typeName
        history {
          eventId
          eventTime
          eventType
        }
      }
    }
    totalCount
  }
}

Get History for Failed Workflows

query {
  workflowHistory(
    where: {
      typeName: "PickingWorkflow"
      status: "FAILED"
    }
    limit: 5
  ) {
    edges {
      node {
        execution {
          workflowId
          id
        }
        typeName
        history {
          eventId
          eventTime
          eventType
          extra
        }
      }
    }
    totalCount
  }
}

Get History by Service and Data Type

query {
  workflowHistory(
    where: {
      service: "picking"
      dataType: "picking-order"
      dataId: "order-123"
    }
  ) {
    edges {
      node {
        execution {
          workflowId
        }
        history {
          eventId
          eventType
          eventTime
        }
      }
    }
  }
}

Example Response

{
  "data": {
    "workflowHistory": {
      "edges": [
        {
          "node": {
            "execution": {
              "workflowId": "picking-order-12345",
              "id": "run-abc-123"
            },
            "typeName": "PickingWorkflow",
            "history": [
              {
                "eventId": 1,
                "eventTime": "2024-01-15T10:30:00Z",
                "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_STARTED",
                "extra": {
                  "workflowType": {
                    "name": "PickingWorkflow"
                  },
                  "taskQueue": {
                    "name": "picking-queue"
                  }
                }
              },
              {
                "eventId": 2,
                "eventTime": "2024-01-15T10:30:01Z",
                "eventType": "EVENT_TYPE_WORKFLOW_TASK_SCHEDULED",
                "extra": {}
              },
              {
                "eventId": 3,
                "eventTime": "2024-01-15T10:30:01Z",
                "eventType": "EVENT_TYPE_WORKFLOW_TASK_STARTED",
                "extra": {}
              },
              {
                "eventId": 4,
                "eventTime": "2024-01-15T10:30:02Z",
                "eventType": "EVENT_TYPE_WORKFLOW_TASK_COMPLETED",
                "extra": {}
              },
              {
                "eventId": 5,
                "eventTime": "2024-01-15T10:30:02Z",
                "eventType": "EVENT_TYPE_ACTIVITY_TASK_SCHEDULED",
                "extra": {
                  "activityType": {
                    "name": "ValidateOrderActivity"
                  }
                }
              }
            ]
          },
          "cursor": "eyJ3b3JrZmxvd0lkIjoicGlja2luZy1vcmRlci0xMjM0NSJ9"
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": false,
        "startCursor": "eyJ3b3JrZmxvd0lkIjoicGlja2luZy1vcmRlci0xMjM0NSJ9",
        "endCursor": "eyJ3b3JrZmxvd0lkIjoicGlja2luZy1vcmRlci0xMjM0NSJ9"
      },
      "totalCount": 1
    }
  }
}

Common Event Types

Event Type	Description
EVENT_TYPE_WORKFLOW_EXECUTION_STARTED	Workflow began execution
EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED	Workflow completed successfully
EVENT_TYPE_WORKFLOW_EXECUTION_FAILED	Workflow failed with error
EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED	Workflow was canceled
EVENT_TYPE_WORKFLOW_EXECUTION_TERMINATED	Workflow was forcefully terminated
EVENT_TYPE_WORKFLOW_EXECUTION_TIMED_OUT	Workflow exceeded timeout
EVENT_TYPE_WORKFLOW_TASK_SCHEDULED	Task scheduled for worker
EVENT_TYPE_WORKFLOW_TASK_STARTED	Worker started task
EVENT_TYPE_WORKFLOW_TASK_COMPLETED	Worker completed task
EVENT_TYPE_ACTIVITY_TASK_SCHEDULED	Activity scheduled
EVENT_TYPE_ACTIVITY_TASK_STARTED	Activity started
EVENT_TYPE_ACTIVITY_TASK_COMPLETED	Activity completed
EVENT_TYPE_ACTIVITY_TASK_FAILED	Activity failed
EVENT_TYPE_TIMER_STARTED	Timer started
EVENT_TYPE_TIMER_FIRED	Timer fired
EVENT_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED	Signal sent to another workflow
EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED	Workflow received signal

Performance Considerations

• The limit parameter defaults to 10 and has a maximum of 100

• Fetching history for many executions can be resource-intensive

• For best performance, query specific workflows by workflowID or runID

• History events are returned in full; there is no pagination within a single execution's history

• Consider using workflowExecutions first to identify specific executions, then query their history

Migration from history Field

If you were previously using the history field on WorkflowExecutionInfo:

Before:

query {
  workflowExecutions(where: { workflowID: "my-workflow" }) {
    execution { workflowId }
    history {
      eventId
      eventType
    }
  }
}

After:

query {
  workflowHistory(where: { workflowID: "my-workflow" }) {
    edges {
      node {
        execution { workflowId }
        history {
          eventId
          eventType
        }
      }
    }
  }
}

Notes

• The where parameter is required - you must specify filter criteria

• Returns all history events for each matching execution (no pagination within history)

• Use the limit parameter to control how many executions' histories are fetched

• This query replaces the removed history field from WorkflowExecutionInfo

• The extra field in history events contains event-specific details

Related Documentation

• workflowExecutions - Query execution metadata

• WorkflowExecutionHistory - History type

• WorkflowExecutionHistoryConnection - Connection type

• WorkflowEvent - Event type

• WorkflowExecutionInfo - Execution info type