> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/graphql-api/queries/workflowhistory.md).

# 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, including support for logical operators (`or`, `and`, `not`) and advanced string predicates.

For complete documentation of all available filters, see [workflowExecutions](/graphql-api/queries/workflowexecutions.md#filter-options-workflowexecutionswhereinput).

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

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

### Get History for Specific Run

```graphql
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

```graphql
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

```graphql
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

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

## Example Response

```json
{
  "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:**

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

**After:**

```graphql
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
* **Logical operators** (`or`, `and`, `not`) are fully supported for building complex filter conditions

## Related Documentation

* [workflowExecutions](/graphql-api/queries/workflowexecutions.md) - Query execution metadata
* [WorkflowExecutionHistory](/graphql-api/types/workflowexecutionhistory.md) - History type
* [WorkflowExecutionHistoryConnection](/graphql-api/types/workflowexecutionhistoryconnection.md) - Connection type
* [WorkflowEvent](/graphql-api/types/workflowevent.md) - Event type
* [WorkflowExecutionInfo](/graphql-api/types/workflowexecutioninfo.md) - Execution info type


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/graphql-api/queries/workflowhistory.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.