---
title: "POST /v2/namespaces/{namespace}/query?stainless_overload=multiQuery"
method: POST
path: "/v2/namespaces/{namespace}/query?stainless_overload=multiQuery"
---

# POST /v2/namespaces/{namespace}/query?stainless_overload=multiQuery

`POST /v2/namespaces/{namespace}/query?stainless_overload=multiQuery`

Issue multiple concurrent queries filter or search documents.

## Path parameters

- `namespace` string, required

## Request body

- object — Configuration options for a query.
  - `vector_encoding` union — The encoding to use for vectors in the response.
    - 'float'
    - 'base64'
  - `consistency` object — The consistency level for a query.
    - `level` union — The query's consistency level.
      - 'strong' — Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
      - 'eventual' — Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
  - `queries` Query[], required
    - `rank_by` unknown
    - `top_k` integer — The number of results to return.
    - `filters` unknown
    - `include_attributes` union — Whether to include attributes in the response.
      - boolean — When `true`, include all attributes in the response. When `false`, include no attributes in the response.
      - string[] — Include exactly the specified attributes in the response.
    - `exclude_attributes` string[] — List of attribute names to exclude from the response. All other attributes will be included in the response.
    - `aggregate_by` object — Aggregations to compute over all documents in the namespace that match the filters.
    - `group_by` unknown[] — Groups documents by the specified attributes (the "group key") before computing aggregates. Aggregates are computed separately for each group.
      - unknown
    - `compute_attributes` object — Computes additional values on documents returned by a query. Each key is the name of the computed attribute; each value is an expression describing how to compute it.
    - `distance_metric` union — A function used to calculate vector similarity.
      - 'cosine_distance' — Defined as `1 - cosine_similarity` and ranges from 0 to 2. Lower is better.
      - 'euclidean_squared' — Defined as `sum((x - y)^2)`. Lower is better.
    - `limit` union
      - integer
      - Limit — Limits the documents returned by a query.
        - `total` integer, required — Limits the total number of documents returned.
        - `per` object — Limits the number of documents with the same value for a set of attributes (the "limit key") that can appear in the results.
          - `attributes` string[], required — The attributes to include in the limit key.
          - `limit` integer, required — The maximum number of documents to return for each value of the limit key.
  - `rerank_by` unknown

## Response `200`

The schema of the namespace.

- MultiQueryResult — The result of a multi-query.
  - `results` SingleQueryResult[], required
    - `aggregations` object
    - `aggregation_groups` AggregationGroup[]
    - `rows` Row[]
      - `id` union, required — An identifier for a document.
        - string, uuid — A UUID.
        - string — A string ID.
        - integer — An integer ID.
      - `vector` union — A vector embedding associated with a document.
        - number[] — A dense vector encoded as an array of floats.
        - string — A dense vector encoded as a base64 string.
  - `performance` QueryPerformance, required — The performance information for a query.
    - `cache_hit_ratio` number, required — The ratio of cache hits to total cache lookups.
    - `cache_temperature` string, required — A qualitative description of the cache hit ratio (`hot`, `warm`, or `cold`).
    - `server_total_ms` integer, required — Request time measured on the server, including time spent waiting for other queries to complete if the namespace was at its concurrency limit.
    - `query_execution_ms` integer, required — Request time measured on the server, excluding time spent waiting due to the namespace concurrency limit.
    - `exhaustive_search_count` integer, required — The number of unindexed documents processed by the query.
    - `approx_namespace_size` integer, required — the approximate number of documents in the namespace.
  - `billing` QueryBilling, required — The billing information for a query.
    - `billable_logical_bytes_queried` integer, required — The number of billable logical bytes queried from the namespace.
    - `billable_logical_bytes_returned` integer, required — The number of billable logical bytes returned from the query.

## Other responses

- `default` — An error response.

---

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