--- 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` ## Request - Base URL: `https://{region}.turbopuffer.com` - URL: `https://{region}.turbopuffer.com/v2/namespaces/{namespace}/query?stainless_overload=multiQuery` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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` union: The consistency level for a query. - object: Strong consistency. Requires a round-trip to object storage to fetch the latest writes. - `level` 'strong', required - object: Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes. - `level` 'eventual', required - `max_staleness_seconds` integer: How long the query may reuse the node's cached view of the namespace before refreshing it from object storage. Defaults to 60. - `queries` Query[], required - `rank_by` unknown - `top_k` integer: The number of results to return. - `offset` integer: Number of documents to skip before returning results. Supported only in v2 queries with an explicit `rank_by` and `top_k` or `limit`. - `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 - `limit` union: Limits the total number of reranked documents returned. - integer: Limits the total number of reranked documents returned. - RerankLimit: Limits the total number of reranked documents returned. - `total` integer, required: Limits the total number of documents returned after reranking. - `offset` integer: Number of reranked documents to skip before returning results. Requires `rerank_by` and `limit`. ## Response `200` The schema of the namespace. - MultiQueryResult: The result of a multi-query. - `results` SingleQueryResult[], required: The results of each subquery, in the same order as `queries`. With `rerank_by`, a single result combining the subqueries' rows. - `aggregations` object - `aggregation_groups` AggregationGroup[] - `rows` Row[]: The documents that matched the query, ordered by `rank_by`. Only present when `rank_by` is set. - `id` union, required: An identifier for a document. - string, uuid: A UUID. - string: A string ID. - integer: An unsigned 64-bit 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. - `embedding_tokens` integer: The number of tokens embedded. Only set when using a native embedding model. - `embedding_ms` integer: Time spent embedding text, in milliseconds. Only set when using a native embedding model. - `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. ## Changes - **2026-10-28** `eaacb7c9194c`: 1 breaking, 2 warning, 2 info - the `allOf[#/components/schemas/QueryConfig]/consistency` request property type changed from `object` to no type - removed the request property `allOf[#/components/schemas/QueryConfig]/consistency/level` - removed the request property `allOf[#/components/schemas/QueryConfig]/consistency/max_staleness_seconds` - added discriminator to `allOf[#/components/schemas/QueryConfig]/consistency` request property - …1 more - **2026-10-27** `f0229c82104e`: 1 info - added the new optional request property `allOf[#/components/schemas/QueryConfig]/consistency/max_staleness_seconds` - **2026-10-16** `c99c9da22ed1`: 6 warning - the `allOf[subschema #2]/limit/anyOf[#/components/schemas/RerankLimit]/total` request property's min was set to `0.00` - the `allOf[subschema #2]/limit/anyOf[subschema #1]/` request property's min was set to `0.00` - the `allOf[subschema #2]/queries/items/limit/anyOf[#/components/schemas/Limit]/per/limit` request property's min was set to `0.00` - the `allOf[subschema #2]/queries/items/limit/anyOf[#/components/schemas/Limit]/total` request property's min was set to `0.00` - …2 more - **2026-10-08** `b7b110f96b73`: 2 info - added the optional property `performance/embedding_ms` to the response with the `200` status - added the optional property `performance/embedding_tokens` to the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/turbopuffer/apis/turbopuffer-api/changes/v2/namespaces/:namespace/query%3Fstainless_overload=multiQuery/post.md) --- [API](https://skmtc.dev/turbopuffer/apis/turbopuffer-api.md) - [All operations](https://skmtc.dev/turbopuffer/apis/turbopuffer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/turbopuffer/apis/turbopuffer-api/revisions/328394035cba?raw)