---
title: "Search active reusable flow references by full-text token query."
method: POST
path: "/flows/references/search"
tags: ["Flow"]
---

# Search active reusable flow references by full-text token query.

`POST /flows/references/search`

Token-based full-text search across flow description (the flow's display name),
annotated step descriptions, GenAI task summary, and labels using the Spanner
SEARCH() function and `idx_flow_reference_search`. Returns rich per-flow rows
ordered by SCORE() descending.

The `query` follows Spanner search syntax — multi-token queries default to AND.
Callers can join keywords with " OR " for broader recall, or quote phrases.

## Query parameters

- `workspace_id` string, required

## Request body

- FlowReferenceTextSearchRequest — Parameters for token-based full-text search over `flow_reference` using the Spanner SEARCH() function and `idx_flow_reference_search`.
  - `query` string, required — Token query. Multi-token defaults to AND; join with " OR " to broaden recall (e.g., "login OR signin OR authentication"). Adjacent tokens are treated as a phrase. Empty query returns zero rows.
  - `search_field` 'combined' | 'description' | 'steps' | 'task_summary' | 'labels' | 'api_endpoint' | 'api_parameters' — Which tokenized column to search. "combined" searches description+steps+task_summary+labels plus api flow url, parameter-name/value, and assertion text. Use a single field name to scope to one column. "description" is the flow's display name. "api_endpoint" scopes to api_steps request URL paths and "api_parameters" to api_steps request parameter names, each optionally paired with a truncated value (e.g. a search for "42" can match a "customerId" parameter valued "42"); both match api-type flows only — browser/mobile flows never match on them ("steps" covers their annotated step text), and flow input parameters are not searched. All fields match whole words (relevance-ranked); partial-word fragments do not match.
  - `application_id` string — Optional. When set, returns flows used by at least one test that resolves to this application (plan membership, training-time application, or recent run history), plus reusable flows used by no test at all (returned with usage_count 0); flows used only by tests that resolve to a different application are excluded. Tests with no discoverable application association are treated as in-scope (the same resolution application-scoped test search uses), so flows used only by such tests stay findable. usage_count reflects usage within this application.
  - `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
  - `label_filter` string[] — Exact-match label filter. When set, only flows whose `labels` array contains every entry in this list are returned. Max 20 entries.
  - `updated_after` string, date-time — Optional. Only return flows edited at or after this timestamp. Backed by the creation time of the flow's latest variant (every flow edit creates a new variant).
  - `include_non_reusable` boolean — When true, include non-reusable flows (inline test-step fragments) in the results. These rows rarely have descriptions and are sparsely indexed, so the default excludes them.
  - `limit` integer, required — Per-call hard limit. Capped at 200 server-side.

## Response `200`

Search results ordered by relevance score (descending).

- FlowReferenceTextSearchResult
  - `matches` FlowReferenceTextSearchMatch[], required — Flows matching the query, ordered by SCORE(combined_tokens, query) descending.
    - `flow_invariant_id` string, required
    - `description` string — The flow description, which serves as the flow's display name.
    - `task_summary` string — GenAI-generated summary of what the flow does.
    - `precondition_summary` string — GenAI-generated summary of the state the flow requires before running.
    - `labels` string[]
    - `flow_type` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile', required — the type of flow
    - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
    - `reusable` boolean, required
    - `usage_count` integer — Number of tests using this flow.
    - `last_updated_time` string, date-time — When the flow was last edited. Derived from the creation time of the latest flow variant.
    - `steps_text` string — The flow's step content. Annotated step descriptions for browser/mobile flows; the api_steps JSON for api-type flows (which have no annotated steps). Server caps the text at a defensive character limit; the calling agent service applies its own adaptive truncation on top.
    - `steps_truncated` boolean — True when steps_text was trimmed by the server-side character cap.
    - `score` number, double, required — Spanner SCORE(combined_tokens, query). Higher = better. Not bounded above.
    - `matched_field` 'combined' | 'description' | 'steps' | 'task_summary' | 'labels' | 'api_endpoint' | 'api_parameters' — The field where the match landed when search_field is not "combined". "api_endpoint" and "api_parameters" only ever appear for api-type flows.
  - `truncated` boolean, required — True if any match's steps_text was trimmed by the server-side character cap. Derived from the per-match steps_truncated flags.

## 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)