---
title: "executeFlowsQuery"
method: POST
path: "/v1/kanban/query/flows:execute"
tags: ["Query"]
---

# executeFlowsQuery

`POST /v1/kanban/query/flows:execute`

Executes a query against the Flows dataset and returns paginated results for use in Kanban card rendering.

Supports filtering with complex AND/OR logic, sorting, and offset-based pagination.
Results are used to populate Kanban swimlane cards with real-time workflow task data.

## Request body

- FlowsQueryRequest — Request payload for executing a query against the Flows dataset. Supports filter conditions, sorting, grouping, and offset-based pagination.
  - `filters` BoardFilter — A filter group containing one or more filter items or nested filter groups. Items are combined using the specified logical operator (AND/OR).
    - `items` union[], required
      - union
        - FilterItem
          - `key` string, required — The field key to filter on
          - `operator` 'EQUALS' | 'NOT_EQUALS' | 'EMPTY' | 'NOT_EMPTY' | 'CONTAINS' | 'NOT_CONTAINS' | 'IS_ONE_OF' | 'IS_NONE_OF' | 'GREATER_THAN' | 'LESS_THAN' | 'GREATER_THAN_OR_EQUAL' | 'LESS_THAN_OR_EQUAL', required — The comparison operator for filtering
          - `value` union — The value to compare against - can be a single value (string, number, boolean, or dynamic date) or an array of values
            - string
            - 'TODAY' | 'TOMORROW' | 'YESTERDAY' | 'IN_THE_FUTURE' | 'IN_THE_PAST' | 'THIS_WEEK' | 'NEXT_WEEK' | 'LAST_WEEK' | 'THIS_MONTH' | 'NEXT_MONTH' | 'LAST_MONTH' | 'TODAY_OR_EARLIER' — Dynamic date keywords that resolve to actual dates at runtime
            - number
            - boolean
            - union[]
              - …
          - `data_type` 'string' | 'number' | 'boolean' | 'date' — The data type of the field
        - FilterGroup
          - `items` FilterItem[], required
            - `key` string, required — The field key to filter on
            - `operator` 'EQUALS' | 'NOT_EQUALS' | 'EMPTY' | 'NOT_EMPTY' | 'CONTAINS' | 'NOT_CONTAINS' | 'IS_ONE_OF' | 'IS_NONE_OF' | 'GREATER_THAN' | 'LESS_THAN' | 'GREATER_THAN_OR_EQUAL' | 'LESS_THAN_OR_EQUAL', required — The comparison operator for filtering
            - `value` union — The value to compare against - can be a single value (string, number, boolean, or dynamic date) or an array of values
              - …
            - `data_type` 'string' | 'number' | 'boolean' | 'date' — The data type of the field
          - `combination` 'AND' | 'OR', required
    - `combination` 'AND' | 'OR', required
  - `sorting` Sorting — Defines how query results should be sorted. Specify a field name and sort direction.
    - `field` string, required
    - `direction` 'asc' | 'desc'
  - `group_by` GroupBy — Defines how tasks should be grouped within each swimlane. Tasks with the same group value are returned adjacently in the result set.
    - `field` 'context_entity' | 'phase' | 'task', required — Property to group tasks by within each swimlane
  - `from` number — Zero-based offset for pagination. Use with `size` to paginate through results.
  - `size` number — Number of results to return per page.

## Response `200`

Query executed successfully

- FlowsQueryResult — Paginated result set returned from a Flows query. Each item in `results` is a workflow task record with dynamic fields depending on the dataset configuration.
  - `results` object[] — Array of matching workflow task records. Fields vary based on the dataset and card configuration.
  - `hits` number — Total number of records matching the query (across all pages).
  - `page_number` number — Current page number (1-based).
  - `page_size` number — Number of results per page (matches the `size` request parameter).
  - `total_pages` number — Total number of available pages based on `hits` and `page_size`.

## Other responses

- `400` — Bad request - Invalid filter or sort configuration
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Insufficient permissions
- `500` — Internal server error

---

[API](https://skmtc.dev/epilot/apis/kanban-api.md) · [All operations](https://skmtc.dev/epilot/apis/kanban-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/epilot/kanban-api/revisions/051153ffb2ea/schema)