> ## Documentation Index > Fetch the complete documentation index at: https://ona.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Workflow Executions > Lists workflow executions with optional filtering. `Unary` ยท [`Workflows`](/docs/api-reference/generated/workflow/overview) Lists workflow executions with optional filtering. Use this method to: * Monitor workflow execution history * Track execution status * Debug workflow issues ### Examples * List executions for workflow: Shows all executions for a specific workflow. ```yaml theme={null} filter: workflowIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] pagination: pageSize: 20 ``` ## Endpoint ```text theme={null} POST /api/gitpod.v1.WorkflowService/ListWorkflowExecutions ``` Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain. ## Request example ```bash cURL theme={null} export ONA_HOST=https://app.ona.com export ONA_API_KEY= curl --request POST \ --url "$ONA_HOST/api/gitpod.v1.WorkflowService/ListWorkflowExecutions" \ --header "Authorization: Bearer $ONA_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "pagination": { "pageSize": 1 } }' ``` ```python Python theme={null} import gitpod.v1.pagination_pb2 as pagination_pb2 import gitpod.v1.workflow_pb2 as workflow_pb2 from ona_sdk import create_client_from_env ona = create_client_from_env() request = workflow_pb2.ListWorkflowExecutionsRequest( pagination=pagination_pb2.PaginationRequest( page_size=1, ), ) response = ona.services.workflow.list_workflow_executions(request) print(response) ``` ```typescript TypeScript theme={null} import { create } from "@bufbuild/protobuf"; import { createClientFromEnv } from "@gitpod/sdk"; import { ListWorkflowExecutionsRequestSchema } from "@gitpod/sdk/gitpod/v1/workflow_pb"; async function main() { const ona = createClientFromEnv(); const request = create(ListWorkflowExecutionsRequestSchema, { pagination: { pageSize: 1, }, }); const response = await ona.services.workflow.listWorkflowExecutions(request); console.log(response); } main().catch(console.error); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "connectrpc.com/connect" "github.com/gitpod-io/gitpod-sdk-go/sdk" gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1" ) func main() { ona, err := sdk.NewFromEnv() if err != nil { log.Fatal(err) } request := connect.NewRequest(&gitpodpb.ListWorkflowExecutionsRequest{ Pagination: &gitpodpb.PaginationRequest{ PageSize: 1, }, }) response, err := ona.Services.Workflow.ListWorkflowExecutions(context.Background(), request) if err != nil { log.Fatal(err) } fmt.Println(response.Msg) } ``` ```json Request body theme={null} { "pagination": { "pageSize": 1 } } ``` ## Request `gitpod.v1.ListWorkflowExecutionsRequest` ListWorkflowExecutionsRequest lists workflow executions with optional filtering. | Field | Type | Required | Description | | ------------ | ----------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request) | No | | | `filter` | [Filter](#type-gitpod-v1-list-workflow-executions-request-filter) | No | | | `sort` | [Sort](#type-gitpod-v1-sort) | No | sort specifies the order of results. When unspecified, results are sorted by operational priority (running first, then failed, then completed, then others). Supported sort fields: startedAt, finishedAt, createdAt. | ## Response `gitpod.v1.ListWorkflowExecutionsResponse` | Field | Type | Required | Description | | -------------------- | ---------------------------------------------------------------- | -------- | ----------- | | `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | | | `workflowExecutions` | array of [WorkflowExecution](#type-gitpod-v1-workflow-execution) | No | | ## Related types `gitpod.v1.ListWorkflowExecutionsRequest.Filter` | Field | Type | Required | Description | | ---------------------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `workflowExecutionIds` | array of string | No | Constraints: `repeated.items.string.uuid=true, repeated.max_items=25`. | | `workflowIds` | array of string | No | Constraints: `repeated.items.string.uuid=true, repeated.max_items=25`. | | `statusPhases` | array of [WorkflowExecutionPhase](#enum-gitpod-v1-workflow-execution-phase) | No | Constraints: `repeated.max_items=10, repeated.min_items=0`. | | `hasFailedActions` | boolean | No | | | `search` | string | No | search performs case-insensitive search across workflow execution ID and trigger type Constraints: `string.max_len=256, string.min_len=0`. | `gitpod.v1.PaginationRequest` | Field | Type | Required | Description | | ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `pageSize` | integer | No | Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. Constraints: `int32.gte=0, int32.lte=100`. | | `token` | string | No | Token for the next set of results that was returned as next\_token of a PaginationResponse | `gitpod.v1.PaginationResponse` | Field | Type | Required | Description | | ----------- | ------ | -------- | --------------------------------------------------------------------------------------- | | `nextToken` | string | No | Token passed for retrieving the next set of results. Empty if there are no more results | `gitpod.v1.Sort` | Field | Type | Required | Description | | ------- | --------------------------------------- | -------- | ------------------------------------ | | `field` | string | No | Field name to sort by, in camelCase. | | `order` | [SortOrder](#enum-gitpod-v1-sort-order) | No | | WorkflowExecution represents a workflow execution instance. `gitpod.v1.WorkflowExecution` | Field | Type | Required | Description | | ---------- | ------------------------------------------------------- | -------- | -------------------------------- | | `id` | string | No | Constraints: `string.uuid=true`. | | `metadata` | [Metadata](#type-gitpod-v1-workflow-execution-metadata) | No | | | `spec` | [Spec](#type-gitpod-v1-workflow-execution-spec) | No | | | `status` | [Status](#type-gitpod-v1-workflow-execution-status) | No | | WorkflowExecutionMetadata contains workflow execution metadata. `gitpod.v1.WorkflowExecution.Metadata` | Field | Type | Required | Description | | ------------ | ------------------ | -------- | -------------------------------- | | `workflowId` | string | No | Constraints: `string.uuid=true`. | | `startedAt` | RFC 3339 timestamp | No | | | `finishedAt` | RFC 3339 timestamp | No | | | `creator` | Subject | No | | | `executor` | Subject | No | | WorkflowExecutionSpec contains the specification used for this execution. `gitpod.v1.WorkflowExecution.Spec` | Field | Type | Required | Description | | -------------- | ------------------------------------------------------------------ | -------- | ----------- | | `session` | string | No | | | `desiredPhase` | [WorkflowExecutionPhase](#enum-gitpod-v1-workflow-execution-phase) | No | | | `trigger` | WorkflowExecutionTrigger | No | | | `action` | WorkflowAction | No | | | `report` | WorkflowAction | No | | WorkflowExecutionStatus contains the current status of a workflow execution. `gitpod.v1.WorkflowExecution.Status` | Field | Type | Required | Description | | -------------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `session` | string | No | | | `phase` | [WorkflowExecutionPhase](#enum-gitpod-v1-workflow-execution-phase) | No | | | `pendingActionCount` | integer | No | | | `runningActionCount` | integer | No | | | `failedActionCount` | integer | No | | | `doneActionCount` | integer | No | | | `stoppedActionCount` | integer | No | | | `failureMessage` | string | No | **Deprecated.** FailureMessage summarises why the workflow execution failed to operate. If this is non-empty the workflow execution has failed to operate and will likely transition to a stopped state. Deprecated: Use failures instead for structured error information. | | `warningMessage` | string | No | **Deprecated.** WarningMessage summarises why the workflow execution is in a warning state. If this is non-empty the workflow execution is in a warning state and likely does not match the users expectations. Deprecated: Use warnings field instead for structured warning information. | | `failures` | array of WorkflowError | No | Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. | | `warnings` | array of WorkflowError | No | Structured warnings about the workflow execution. Provides detailed warning codes and messages. | | Value | Number | Description | | ------------------------ | -----: | ----------- | | `SORT_ORDER_UNSPECIFIED` | 0 | | | `SORT_ORDER_ASC` | 1 | | | `SORT_ORDER_DESC` | 2 | | | Value | Number | Description | | -------------------------------------- | -----: | ----------- | | `WORKFLOW_EXECUTION_PHASE_UNSPECIFIED` | 0 | | | `WORKFLOW_EXECUTION_PHASE_PENDING` | 1 | | | `WORKFLOW_EXECUTION_PHASE_RUNNING` | 2 | | | `WORKFLOW_EXECUTION_PHASE_STOPPING` | 3 | | | `WORKFLOW_EXECUTION_PHASE_STOPPED` | 4 | | | `WORKFLOW_EXECUTION_PHASE_DELETING` | 5 | | | `WORKFLOW_EXECUTION_PHASE_DELETED` | 6 | | | `WORKFLOW_EXECUTION_PHASE_COMPLETED` | 7 | |