---
title: "Query flows by task"
method: POST
path: "/flows/references/task"
tags: ["Flow"]
---

# Query flows by task

`POST /flows/references/task`

Used to query flows by task using flow references for most recent main version

## Query parameters

- `workspace_id` string, required

## Request body

- QueryEntityByTaskParameters — Parameters for querying entities by task description
  - `application_id` string — Restricts the query to entities of a given application ID
  - `database_connection_id` string — Restricts the query to entities with the given database connection ID (only used for Snippet queries)
  - `flow_type` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile' — the type of flow
  - `limit` integer, required — The max results to return
  - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
  - `reusable` boolean — If specified, will only return entities with the given reusable flag
  - `snippet_types` SnippetTypeEnum[] — Restricts the query to entities with the given snippet type (only used for Snippet queries)
  - `session_id` string — The id of the mabl AI session, if any
  - `task_description` string, required — The task description
  - `rerank_with_llm` boolean — When true (default), the candidate list is LLM-reranked against the task description before the top `limit` are returned. When false, the LLM rerank is skipped and the raw datastore-ordered candidates (ASC by `COSINE_DISTANCE`) are returned. Either way the response honors `limit`; the internal candidate widening multiplier varies by endpoint (endpoints that group results after the fetch keep the widened set so grouping does not underfill `limit`).

## Response `200`

Array of flows matching the query

- FlowQueryResult
  - `flows` Flow[] — All flows that matched the query
    - `id` string — Unique identifier
    - `created_by_id` string — The ID of the user who created this test
    - `last_updated_time` integer — Time the test was last updated in epoch milliseconds
    - `last_updated_by_id` string — The ID of the user who last updated this test
    - `created_time` integer — Time the test was created in epoch milliseconds
    - `revision_history` string — Serialized graph describing the test's version history. Managed by mabl API only.
    - `version_tags` object — Mapping of version tags to version numbers that the tag is currently applied to
    - `latest_version` integer — The latest numeric version of this test
    - `organization_id` string — (deprecated) The ID of the organization that this journey belongs to
    - `workspace_id` string — Workspace Id
    - `flow_type` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile' — the type of flow
    - `reusable` boolean — Indicates whether this can be used by multiple tests
    - `description` string — Summary of the flow
    - `labels` Label[] — User provided labels
      - `name` string, required — name
      - `color` string — color
    - `source_control_tags` object — mapping of tags to version numbers the tag is currently applied to
    - `import_source_id` 'postman' | 'selenium_node_proxy' | 'selenium_java_agent'
    - `import_source_version` string — Version of the import tool used to import this flow
    - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
    - `minimize_execution_overhead` boolean — When enabled, mabl will not capture screenshots, network logs, DOM snapshots, or other test artifacts in order to report the most accurate flow execution time
    - `is_latest` boolean — Indicates whether this was the latest variant when retrieved
    - `version` integer — The generation number of this variant
    - `previous_version` integer — The generation number of the variant that was edited to create this variant (if applicable)
    - `merged_version` integer — The generation number of the variant that was merged with the previous version to create this variant (if applicable)
    - `merged_from_branch` string — Name of the source branch whose version was merged to create this variant (if applicable)
    - `created_on_branch` string — Branch name the test was created on
    - `change_description` string — Description of the change between this variant and the previous variant
    - `variant_last_updated_by_app_version` string — The version of the desktop app used to create this version.
    - `script` string — The flow's script
    - `script_description` string — Description of what the script does
    - `step_annotations` object — Step descriptions and notes keyed by the step index
    - `selectors` string[] — the selectors from mablscript
    - `file_references` FileReference[] — the file references from mablscript
      - `id` string, required — The ID of the uploaded file
      - `name` string — the base file name
      - `size` integer — the size of the file
      - `type` string — the type of the file, i.e., the extension
    - `flow_references` FlowReference[] — reusable flows referenced by steps in this flow
      - `invariantId` string, required — The ID of a referenced flow
      - `flowType` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile' — the type of flow
      - `flow` Flow — recursive
    - `snippet_references` SnippetReference[] — this snippets referenced by this Flow
      - `id` string, required — The ID of the snippet invariant used
      - `snippetType` 'css' | 'javascript' | 'xpath' | 'sql' | 'postman'
    - `variables` UserDefinedVariables
      - `inputs` UserDefinedInputVariable[] — the input variables for the flow/test (used before they are defined) with set semantics on name
        - `name` string, required — the fully qualified symbol name of the variable
        - `default_value` string — the value to use when the variable is not otherwise defined
        - `value_type` 'string' | 'file' — The kind of value this variable carries. Absent implies `string` for backward compatibility; existing string variables are unaffected.
        - `file_value` FileValue — A typed file value for a file-typed variable, reconciling field-for-field with the runtime FileValue (mabl-cli mablscript-find). `origin` selects which reference is populated: `upload` uses file_upload_id, `download` uses download_ref. This one-of invariant is NOT enforced by the schema (a oneOf/discriminator would make the generated Java/TS clients polymorphic and diverge from the flat runtime FileValue); it must be enforced by validation on the Flow/Test write path, tracked in MABL-20387, before file variables are consumed (first reader: MABL-20718). Until then a malformed file_value is accepted but unused. The run-local localUri from the runtime shape is intentionally omitted (ephemeral, never persisted).
          - `origin` 'upload' | 'download', required — Provenance of the file. `upload` is a durable, reusable FileUpload (see file_upload_id). `download` is a transient file produced by a test run (see download_ref).
          - `name` string, required — the base file name
          - `mime_type` string, required — the true MIME type (e.g. application/pdf), not a file extension
          - `size` integer, required — the size of the file in bytes
          - `checksum` string — optional content checksum
          - `file_upload_id` string — Set when origin == upload; the id of a durable FileUpload (FileUpload.id). This is how a persisted or authored file variable references its file.
          - `download_ref` FileDownloadReference — Run-scoped coordinates locating a file downloaded during a test run. The backend derives the workspace from test_run_id and reconstructs the artifact location from object_key server-side; the bucket name is never stored here or returned to clients. Valid only within the producing run's artifact-retention window.
            - `id` string — stable logical handle for this downloaded file within the producing run
            - `test_run_id` string, required — the id of the test run that produced this download
            - `object_key` string, required — Bucket-relative storage key (e.g. execution-output/<nonce>/downloads/<run>/<step>/<name>). Excludes the bucket name; the backend prepends the workspace bucket at resolution time.
      - `outputs` UserDefinedOutputVariable[] — the variables defined by this script with set semantics. this is not used by the test.
        - `name` string, required — the fully qualified symbol name of the variable
    - `parameters` UserDefinedInputVariable[] — Configurable parameters mapping parameter name to a default value for that parameter
      - `name` string, required — the fully qualified symbol name of the variable
      - `default_value` string — the value to use when the variable is not otherwise defined
      - `value_type` 'string' | 'file' — The kind of value this variable carries. Absent implies `string` for backward compatibility; existing string variables are unaffected.
      - `file_value` FileValue — A typed file value for a file-typed variable, reconciling field-for-field with the runtime FileValue (mabl-cli mablscript-find). `origin` selects which reference is populated: `upload` uses file_upload_id, `download` uses download_ref. This one-of invariant is NOT enforced by the schema (a oneOf/discriminator would make the generated Java/TS clients polymorphic and diverge from the flat runtime FileValue); it must be enforced by validation on the Flow/Test write path, tracked in MABL-20387, before file variables are consumed (first reader: MABL-20718). Until then a malformed file_value is accepted but unused. The run-local localUri from the runtime shape is intentionally omitted (ephemeral, never persisted).
        - `origin` 'upload' | 'download', required — Provenance of the file. `upload` is a durable, reusable FileUpload (see file_upload_id). `download` is a transient file produced by a test run (see download_ref).
        - `name` string, required — the base file name
        - `mime_type` string, required — the true MIME type (e.g. application/pdf), not a file extension
        - `size` integer, required — the size of the file in bytes
        - `checksum` string — optional content checksum
        - `file_upload_id` string — Set when origin == upload; the id of a durable FileUpload (FileUpload.id). This is how a persisted or authored file variable references its file.
        - `download_ref` FileDownloadReference — Run-scoped coordinates locating a file downloaded during a test run. The backend derives the workspace from test_run_id and reconstructs the artifact location from object_key server-side; the bucket name is never stored here or returned to clients. Valid only within the producing run's artifact-retention window.
          - `id` string — stable logical handle for this downloaded file within the producing run
          - `test_run_id` string, required — the id of the test run that produced this download
          - `object_key` string, required — Bucket-relative storage key (e.g. execution-output/<nonce>/downloads/<run>/<step>/<name>). Excludes the bucket name; the backend prepends the workspace bucket at resolution time.
    - `step_features` StepFeature[] — Steps that are associated with specific features
      - `step_index` integer — Index of the step
      - `nested_step_index` integer[] — Array of indices representing the path to nested steps within StepGroups. Empty for top-level steps.
      - `feature_id` string — Id of the Feature is that is associated with this particular step.
    - `page_urls` string[] — URLs that should be visited for a visual page checker test
    - `api_steps` object — API steps for API only flow (stored in postman collection format)
    - `json_steps` object — Steps in the new json format that replaces mablscript
    - `mobile_training_info` MobileTrainingInfo
      - `device_name` string — The name of the mobile device
      - `device_api_level` string — The API level of the mobile device
      - `device_os_version` string — The OS version of the mobile device
      - `screen_dimensions` DeviceScreenDimensions
        - `height` integer, required — Height (pixels)
        - `width` integer, required — Width (pixels)
      - `is_cloud_training` boolean — Whether the training took place on a cloud device or local device
      - `is_real_device` boolean — Whether the training took place on a real device or an emulator/simulator
      - `app_file_name` string — The mobile app file name (only present for local training)
      - `app_file_id` string — The file id of the mobile app (only present for cloud training)
    - `created_by_app_version` string — The version of the desktop app used to create this version.
    - `url` string — the URL used when creating the flow
    - `agent_session_id` string — the id of the agent session that authored this flow version, if any
    - `variant_last_updated_time` integer — Time the variant was last updated
    - `variant_last_updated_by_id` string — ID of the user who last updated the variant
    - `cloud_safe_invariant_id` string — Cloud safe ID representation (e.g. GCP/email/Kubernetes safe)
    - `invariant_id` string — Object ID for the parent type. Set by system.
  - `flow_summaries` FlowSummary[] — Flow summaries, when relevant
    - `workspace_id` string — The workspace ID of the flow
    - `flow_invariant_id` string — The invariant ID of the flow
    - `flow_annotated_steps` string — The flow steps with annotations
    - `flow_summary` string — The GenAI flow summary
    - `flow_preconditions` string — The GenAI summary of the flow preconditions
    - `flow_description` string — The flow description
    - `usage_count` integer — The number of tests using this flow
    - `labels` string[] — User provided labels on the flow.
    - `flow_type` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile' — the type of flow
    - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
    - `reusable` boolean — Whether this flow can be used by multiple tests.
    - `distance` number, double — Cosine distance between the query embedding and the flow's task embedding. Lower = more similar. Only populated by semantic (by-task) queries.
    - `last_updated_time` string, date-time — When the flow was last edited. Derived from the creation time of the latest flow variant (every flow edit creates a new variant).
  - `cursor` string — Cursor used for pagination

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)