> 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/types/workflowevent.md).

# WorkflowEvent

WorkflowEvent Type - Individual event in workflow execution history

Audience: Programmer

The WorkflowEvent type represents a single event in a Temporal workflow's execution history. Each event captures a specific action or state change that occurred during workflow execution, providing a detailed audit trail of the workflow's progress.

## Fields

| Field       | Type      | Description                                                               |
| ----------- | --------- | ------------------------------------------------------------------------- |
| `eventId`   | `Int!`    | Sequential identifier for the event within the workflow history           |
| `eventTime` | `String!` | ISO 8601 timestamp when the event occurred                                |
| `eventType` | `String!` | The type of event (e.g., WorkflowExecutionStarted, ActivityTaskScheduled) |
| `extra`     | `Map`     | Additional event-specific attributes and data                             |

## Service

This type is defined in the **Workflow** service.

## Event Types

Temporal workflows generate various event types throughout their execution. Common event types include:

### Workflow Lifecycle Events

| Event Type                                 | Description                        |
| ------------------------------------------ | ---------------------------------- |
| `EVENT_TYPE_WORKFLOW_EXECUTION_STARTED`    | Workflow execution has begun       |
| `EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED`  | Workflow completed successfully    |
| `EVENT_TYPE_WORKFLOW_EXECUTION_FAILED`     | Workflow failed with an error      |
| `EVENT_TYPE_WORKFLOW_EXECUTION_TIMED_OUT`  | Workflow exceeded its timeout      |
| `EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED`   | Workflow was canceled              |
| `EVENT_TYPE_WORKFLOW_EXECUTION_TERMINATED` | Workflow was forcefully terminated |

### Activity Events

| Event Type                           | Description                          |
| ------------------------------------ | ------------------------------------ |
| `EVENT_TYPE_ACTIVITY_TASK_SCHEDULED` | Activity task has been scheduled     |
| `EVENT_TYPE_ACTIVITY_TASK_STARTED`   | Activity task execution started      |
| `EVENT_TYPE_ACTIVITY_TASK_COMPLETED` | Activity task completed successfully |
| `EVENT_TYPE_ACTIVITY_TASK_FAILED`    | Activity task failed                 |
| `EVENT_TYPE_ACTIVITY_TASK_TIMED_OUT` | Activity task exceeded its timeout   |

### Timer Events

| Event Type                  | Description            |
| --------------------------- | ---------------------- |
| `EVENT_TYPE_TIMER_STARTED`  | Timer has been started |
| `EVENT_TYPE_TIMER_FIRED`    | Timer has fired        |
| `EVENT_TYPE_TIMER_CANCELED` | Timer was canceled     |

### Workflow Task Events

| Event Type                           | Description                      |
| ------------------------------------ | -------------------------------- |
| `EVENT_TYPE_WORKFLOW_TASK_SCHEDULED` | Workflow task has been scheduled |
| `EVENT_TYPE_WORKFLOW_TASK_STARTED`   | Workflow task execution started  |
| `EVENT_TYPE_WORKFLOW_TASK_COMPLETED` | Workflow task completed          |

## Usage Example

### Query Workflow Execution with History

```graphql
query GetWorkflowHistory {
  workflowExecutions(
    where: {
      workflowID: "picking-order-12345"
    }
  ) {
    execution {
      workflowId
      id
    }
    type {
      name
    }
    status
    startTime
    closeTime
    historyLength
    history {
      eventId
      eventTime
      eventType
      extra
    }
  }
}
```

### Query Recent Activity Events

```graphql
query GetWorkflowActivities {
  workflowExecutions(
    where: {
      typeName: "PickingWorkflow"
      status: "RUNNING"
    }
  ) {
    execution {
      workflowId
    }
    searchAttributes {
      key
      value
    }
    history {
      eventId
      eventTime
      eventType
      extra
    }
  }
}
```

### Example Response

```json
{
  "data": {
    "workflowExecutions": [
      {
        "execution": {
          "workflowId": "picking-order-12345",
          "id": "run-abc-123"
        },
        "type": {
          "name": "PickingWorkflow"
        },
        "status": "RUNNING",
        "startTime": "2024-01-15T10:30:00Z",
        "closeTime": null,
        "historyLength": 12,
        "history": [
          {
            "eventId": 1,
            "eventTime": "2024-01-15T10:30:00Z",
            "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_STARTED",
            "extra": {
              "workflowType": {
                "name": "PickingWorkflow"
              },
              "taskQueue": {
                "name": "picking-queue"
              },
              "input": null,
              "workflowExecutionTimeout": "3600s",
              "workflowRunTimeout": "3600s"
            }
          },
          {
            "eventId": 2,
            "eventTime": "2024-01-15T10:30:00Z",
            "eventType": "EVENT_TYPE_WORKFLOW_TASK_SCHEDULED",
            "extra": {
              "taskQueue": {
                "name": "picking-queue"
              },
              "startToCloseTimeout": "10s"
            }
          },
          {
            "eventId": 3,
            "eventTime": "2024-01-15T10:30:01Z",
            "eventType": "EVENT_TYPE_WORKFLOW_TASK_STARTED",
            "extra": {
              "scheduledEventId": "2",
              "identity": "worker-1@picking-service"
            }
          },
          {
            "eventId": 4,
            "eventTime": "2024-01-15T10:30:01Z",
            "eventType": "EVENT_TYPE_WORKFLOW_TASK_COMPLETED",
            "extra": {
              "scheduledEventId": "2",
              "startedEventId": "3"
            }
          },
          {
            "eventId": 5,
            "eventTime": "2024-01-15T10:30:01Z",
            "eventType": "EVENT_TYPE_ACTIVITY_TASK_SCHEDULED",
            "extra": {
              "activityId": "1",
              "activityType": {
                "name": "ValidatePickingOrder"
              },
              "taskQueue": {
                "name": "picking-queue"
              },
              "scheduleToCloseTimeout": "300s",
              "scheduleToStartTimeout": "60s",
              "startToCloseTimeout": "240s"
            }
          },
          {
            "eventId": 6,
            "eventTime": "2024-01-15T10:30:02Z",
            "eventType": "EVENT_TYPE_ACTIVITY_TASK_STARTED",
            "extra": {
              "scheduledEventId": "5",
              "identity": "worker-2@picking-service"
            }
          },
          {
            "eventId": 7,
            "eventTime": "2024-01-15T10:30:05Z",
            "eventType": "EVENT_TYPE_ACTIVITY_TASK_COMPLETED",
            "extra": {
              "scheduledEventId": "5",
              "startedEventId": "6",
              "result": null
            }
          }
        ]
      }
    ]
  }
}
```

## JavaScript Example

```javascript
// Fetch workflow history and analyze events
const response = await client.query({
  query: gql`
    query GetWorkflowHistory($workflowId: String!) {
      workflowExecutions(
        where: { workflowID: $workflowId }
      ) {
        execution {
          workflowId
          id
        }
        status
        history {
          eventId
          eventTime
          eventType
          extra
        }
      }
    }
  `,
  variables: {
    workflowId: "picking-order-12345"
  }
});

const workflow = response.data.workflowExecutions[0];
const history = workflow.history;

// Filter for activity events
const activityEvents = history.filter(event =>
  event.eventType.includes('ACTIVITY')
);

// Find failed activities
const failedActivities = history.filter(event =>
  event.eventType === 'EVENT_TYPE_ACTIVITY_TASK_FAILED'
);

// Calculate workflow duration from events
const startEvent = history.find(e =>
  e.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_STARTED'
);
const endEvent = history.find(e =>
  e.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED'
);

if (startEvent && endEvent) {
  const duration = new Date(endEvent.eventTime) - new Date(startEvent.eventTime);
  console.log(`Workflow completed in ${duration}ms`);
}
```

## Use Cases

### Debugging Failed Workflows

Query the history to identify where a workflow failed:

```graphql
query DebugFailedWorkflow {
  workflowExecutions(
    where: {
      workflowID: "failed-workflow-123"
      status: "FAILED"
    }
  ) {
    execution {
      workflowId
    }
    history {
      eventId
      eventTime
      eventType
      extra
    }
  }
}
```

### Monitoring Activity Performance

Analyze activity durations by examining the time between SCHEDULED, STARTED, and COMPLETED events.

### Audit Trail

The history provides a complete audit trail of all actions taken during workflow execution, useful for compliance and debugging.

## Related Types

* [WorkflowExecutionInfo](/graphql-api/types/workflowexecutioninfo.md) - Parent type containing the history field
* [TemporalMetadata](/graphql-api/types/temporalmetadata.md) - Key-value metadata for search attributes
* [Workflow](/graphql-api/types/workflow.md) - Workflow definition type

## Notes

* The `eventId` field is sequential within a workflow execution, starting at 1
* Event times are in ISO 8601 format (RFC3339)
* The `extra` field contains event-specific attributes that vary by event type
* History events are ordered chronologically by `eventId`
* Large workflows may have extensive histories; use `historyLength` to gauge size before fetching
* The history is fetched directly from Temporal and reflects the complete execution state
* Event types follow Temporal's naming convention with the `EVENT_TYPE_` prefix


---

# 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/types/workflowevent.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.