> ## 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 Workflows
> Call gitpod.v1.WorkflowService.ListWorkflows.
`Unary` ยท [`Workflows`](/docs/api-reference/generated/workflow/overview)
## Endpoint
```text theme={null}
POST /api/gitpod.v1.WorkflowService/ListWorkflows
```
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/ListWorkflows" \
--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.ListWorkflowsRequest(
pagination=pagination_pb2.PaginationRequest(
page_size=1,
),
)
response = ona.services.workflow.list_workflows(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListWorkflowsRequestSchema } from "@gitpod/sdk/gitpod/v1/workflow_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListWorkflowsRequestSchema, {
pagination: {
pageSize: 1,
},
});
const response = await ona.services.workflow.listWorkflows(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.ListWorkflowsRequest{
Pagination: &gitpodpb.PaginationRequest{
PageSize: 1,
},
})
response, err := ona.Services.Workflow.ListWorkflows(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"pagination": {
"pageSize": 1
}
}
```
## Request
`gitpod.v1.ListWorkflowsRequest`
ListWorkflowsRequest lists workflows with optional filtering.
| Field | Type | Required | Description |
| ------------ | ------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request) | No | |
| `filter` | [Filter](#type-gitpod-v1-list-workflows-request-filter) | No | |
| `sort` | [Sort](#type-gitpod-v1-list-workflows-request-sort) | No | sort specifies the order of results. When unspecified, results are sorted alphabetically by name ascending. |
| `count` | [CountRequest](#type-gitpod-v1-count-request) | No | count controls whether the response includes a bounded total count. |
## Response
`gitpod.v1.ListWorkflowsResponse`
| Field | Type | Required | Description |
| ------------ | --------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | |
| `workflows` | array of [Workflow](#type-gitpod-v1-workflow) | No | |
| `count` | [CountResponse](#type-gitpod-v1-count-response) | No | count is the bounded total count of matching workflows, present only when requested via CountRequest.include on the first page. |
## Related types
CountRequest controls whether the response should include a bounded
count of matching records.
`gitpod.v1.CountRequest`
| Field | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | boolean | No | When true, the first page of results will include a CountResponse with the bounded total. Subsequent pages (requests with a pagination token) will not contain the count. |
CountResponse represents a bounded count of matching records.
When the actual count exceeds the counting limit, value is capped and
relation is set to GREATER\_THAN\_OR\_EQUAL.
`gitpod.v1.CountResponse`
| Field | Type | Required | Description |
| ---------- | ---------------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
| `value` | integer | No | The count of matching records, capped at the server's counting limit. |
| `relation` | [CountResponseRelation](#enum-gitpod-v1-count-response-relation) | No | Indicates whether value is the exact total or a lower bound. |
`gitpod.v1.ListWorkflowsRequest.Filter`
| Field | Type | Required | Description |
| ------------------------- | --------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflowIds` | array of string | No | Constraints: `repeated.items.string.uuid=true, repeated.max_items=25`. |
| `search` | string | No | search performs case-insensitive search across workflow name, description, and ID Constraints: `string.max_len=256, string.min_len=0`. |
| `creatorIds` | array of string | No | creator\_ids filters workflows by creator user IDs Constraints: `repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0`. |
| `statusPhases` | array of [WorkflowExecutionPhase](#enum-gitpod-v1-workflow-execution-phase) | No | status\_phases filters workflows by the phase of their latest execution. Only workflows whose most recent execution matches one of the specified phases are returned. Constraints: `repeated.max_items=10, repeated.min_items=0`. |
| `hasFailedExecutionSince` | RFC 3339 timestamp | No | has\_failed\_execution\_since filters workflows that have at least one failed execution with create\_time >= the specified timestamp. A failed execution is one that is COMPLETED with failed\_action\_count > 0, or STOPPED with failed\_action\_count > 0 or a non-empty failure\_message. This filter is mutually exclusive with status\_phases. |
| `disabled` | boolean | No | disabled filters workflows by their disabled state. When set to true, only disabled workflows are returned. When set to false, only enabled workflows are returned. When unset, all workflows are returned regardless of disabled state. |
`gitpod.v1.ListWorkflowsRequest.Sort`
| Field | Type | Required | Description |
| ------- | -------------------------------------------------------------- | -------- | ----------- |
| `field` | [SortField](#enum-gitpod-v1-list-workflows-request-sort-field) | No | |
| `order` | [SortOrder](#enum-gitpod-v1-sort-order) | No | |
`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 |
Workflow represents a workflow configuration.
`gitpod.v1.Workflow`
| Field | Type | Required | Description |
| ------------ | --------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `id` | string | No | Constraints: `string.uuid=true`. |
| `metadata` | [Metadata](#type-gitpod-v1-workflow-metadata) | No | |
| `spec` | [Spec](#type-gitpod-v1-workflow-spec) | No | |
| `webhookUrl` | string | No | Webhook URL for triggering this workflow via HTTP POST Format: \{base\_url}/workflows/\{workflow\_id}/webhooks |
WorkflowMetadata contains workflow metadata.
`gitpod.v1.Workflow.Metadata`
| Field | Type | Required | Description |
| ------------- | ------------------ | -------- | --------------------------------------------------- |
| `name` | string | No | Constraints: `string.max_len=80, string.min_len=1`. |
| `description` | string | No | Constraints: `string.max_len=500`. |
| `creator` | Subject | No | |
| `executor` | Subject | No | |
| `createdAt` | RFC 3339 timestamp | No | |
| `updatedAt` | RFC 3339 timestamp | No | |
`gitpod.v1.Workflow.Spec`
| Field | Type | Required | Description |
| --------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `triggers` | array of WorkflowTrigger | No | |
| `action` | WorkflowAction | No | |
| `report` | WorkflowAction | No | |
| `deleting` | boolean | No | Marks workflow as pending deletion |
| `disabled` | boolean | No | When true, the workflow will not be triggered by any automatic trigger (cron, webhook, pull request). Manual starts via StartWorkflow are also rejected while disabled. |
| `agentId` | string | No | Agent that runs this workflow. When empty, the agent is resolved at run time (defaults to the Ona agent), preserving behavior for workflows created before agent selection existed. |
| `codexSettings` | CodexSettings | No | Codex app agent settings (model, reasoning effort, service tier). Only meaningful when agent\_id refers to the Codex app agent. |
| Value | Number | Description |
| ------------------------------------- | -----: | ---------------------------------------------------------------------------- |
| `COUNT_RESPONSE_RELATION_UNSPECIFIED` | 0 | |
| `COUNT_RESPONSE_RELATION_EQ` | 1 | The count is equal to the number of matching records. |
| `COUNT_RESPONSE_RELATION_GTE` | 2 | The actual number of matching records is greater than or equal to the value. |
| Value | Number | Description |
| ------------------------------- | -----: | ---------------------------------------------------------------------------------------------------- |
| `SORT_FIELD_UNSPECIFIED` | 0 | |
| `SORT_FIELD_NAME` | 1 | Sort alphabetically by workflow name. |
| `SORT_FIELD_RECENTLY_COMPLETED` | 2 | Sort by the most recent terminal execution's finished\_at. Workflows with no executions appear last. |
| 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 | |