---
title: "Search active test references by full-text token query."
method: POST
path: "/test/references/search"
tags: ["Test"]
---

# Search active test references by full-text token query.

`POST /test/references/search`

Token-based full-text search across test name, description, intent, and labels
using the Spanner SEARCH() function and `idx_test_reference_search`. Returns
rich per-test rows (including concatenated annotated step descriptions joined
through `test_reference.flows` -> `flow_reference`) ordered by SCORE() desc.

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

- TestReferenceTextSearchRequest — Parameters for token-based full-text search over `test_reference` using the Spanner SEARCH() function and `idx_test_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' | 'name' | 'description' | 'intent' | 'labels' — Which tokenized column to search. "combined" searches name+description+intent+labels. Use a single field name to scope to a specific column.
  - `application_id` string — Optional. When set, only return tests scoped to this application.
  - `test_type` 'api' | 'browser' | 'performance' | 'mobile' — Type of test
  - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
  - `label_filter` string[] — Exact-match label filter. When set, only tests whose `labels` array contains every entry in this list are returned. Max 20 entries.
  - `updated_after` string, date-time — Optional. Only return tests with last_updated_time >= this timestamp.
  - `limit` integer, required — Per-call hard limit. Capped at 200 server-side.

## Response `200`

Search results ordered by relevance score (descending).

- TestReferenceTextSearchResult
  - `matches` TestReferenceTextSearchMatch[], required — Tests matching the query, ordered by SCORE(combined_tokens, query) descending.
    - `test_invariant_id` string, required
    - `test_name` string, required
    - `description` string
    - `labels` string[]
    - `intent` string — TAA-generated intent string (often empty until Dataflow writer fills it).
    - `test_type` 'api' | 'browser' | 'performance' | 'mobile', required — Type of test
    - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
    - `application_id` string
    - `last_updated_time` string, date-time
    - `annotated_step_text` string — Concatenation of each flow's annotated_step_descriptions in test order. Server caps the text at a defensive character limit applied both per flow and over the full concatenation; the calling agent service applies its own adaptive truncation on top.
    - `annotated_step_truncated` boolean — True when annotated_step_text was trimmed by the server-side character cap at either level (an individual flow exceeded the per-flow cap, or the full concatenation exceeded the per-row cap). False when the text is complete.
    - `score` number, double, required — Spanner SCORE(combined_tokens, query). Higher = better. Not bounded above.
    - `matched_field` 'combined' | 'name' | 'description' | 'intent' | 'labels' — The field where the match landed when search_field is not "combined".
  - `truncated` boolean, required — True if any match's annotated_step_text was trimmed by the server-side character cap at either level (per-flow or total). Derived from the per-match annotated_step_truncated flags. The agent-side adaptive truncation re-truncates against a total tool-response budget.

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