---
title: "Query tests by chunk"
method: POST
path: "/test/references/chunk"
tags: ["Test"]
---

# Query tests by chunk

`POST /test/references/chunk`

Used to query tests using test step chunks 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 tests matching the query

- TestSemanticQueryResult
  - `tests` TestSemanticQueryMatch[], required — All tests that matched the query
    - `test_invariant_id` string, required — The test invariant ID associated with this match
    - `test_name` string
    - `test_description` string
    - `test_type` 'api' | 'browser' | 'performance' | 'mobile' — Type of test
    - `application_id` string — The application this test is associated with, if any.
    - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
    - `labels` string[] — Labels attached to this test (e.g., "smoke", "regression").
    - `intent` string — TAA-generated intent string for the test (often empty until the Dataflow writer fills it).
    - `last_updated_time` string, date-time — ISO-8601 timestamp of the last update to the test.
    - `created_by_id` string — User ID of the test's creator.
    - `last_updated_by_id` string — User ID of the last user to update the test.
    - `test_step_chunks` TestStepChunkMatch[], required — All test step chunks associated with this test that matched the query
      - `annotated_step_descriptions` string, required — Detailed description of the steps in this chunk
      - `context` string, required — A brief summary of what this chunk does
      - `flow_invariant_id` string, required — The flow invariant ID associated with this chunk
      - `flow_step_end_index` integer, required — The end index of the flow step in this chunk
      - `flow_step_start_index` integer, required — The start index of the flow step in this chunk
      - `reusable_flow` boolean — True when the chunk's steps live in a reusable flow, false when they are an inline (non-reusable) test-step fragment. Lets a consumer anchor a coverage link on the flow (reusable) versus the containing test position (non-reusable).
      - `distance` number, double — Cosine distance between the query embedding and this chunk's embedding. Lower = more similar. Only populated by semantic (by-task) chunk queries; absent for non-semantic paths. A support signal for the consumer to weigh, not a ranking the API applies.

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